4.9 KiB

Raw Permalink Blame History

HappyWedding 生产运维说明（Docker 容器）

本文档对应 HappyWedding（hw）在 Linux 主机上以 Python 3.13 容器 + Gunicorn 方式运行时的日常运维操作。

1. 服务组成

线上服务主要由以下部分组成：

hw 容器
- 由 Docker 运行
- 容器内启动 Gunicorn
- Gunicorn 加载 run:app
- 容器启动时自动执行数据库迁移

运维前提：Docker CLI 可用且 Docker daemon 已启动。

数据库
- 推荐 MySQL
- 连接串由 /opt/hw.conf.d/hw.env 中的 DATABASE_URL 控制
宿主持久化目录
- /opt/hw/instance
- /opt/hw/instance/csv_previews

如需 HTTPS 或域名接入，可在容器前自行挂 nginx / Caddy / 负载均衡；本文档只覆盖应用容器本身。

2. 日常查看命令

2.1 查看容器状态

docker ps --filter name=hw

2.2 查看容器日志

docker logs -f hw

查看最近 200 行：

docker logs --tail 200 hw

2.3 查看健康检查

docker inspect --format '{{json .State.Health}}' hw

2.4 查看健康检查接口

curl -fsS http://127.0.0.1:8000/health

如你发布到了其他端口：

curl -fsS http://127.0.0.1:<your-port>/health

3. 常规发布流程

假设你已经把最新代码同步到 /opt/hw：

cd /opt/hw
sudo bash scripts/deploy-container.sh
sudo bash scripts/verify-container-deployment.sh

建议的发布后检查：

docker ps --filter name=hw
docker logs --tail 100 hw
curl -fsS http://127.0.0.1:8000/health
打开浏览器访问首页和登录页

4. 首次初始化基础数据

仅在数据库是全新空库时执行：

cd /opt/hw
sudo RUN_SEED_ALL=1 bash scripts/deploy-container.sh

已有生产数据时，不要重复无脑执行 seed-all。当前脚本会通过 /opt/hw/instance/.seed-all-complete 做一次性标记，但生产环境仍应谨慎操作。

5. 修改环境变量后的操作

如果你修改了 /opt/hw.conf.d/hw.env，需要重新部署容器让其生效：

cd /opt/hw
sudo bash scripts/deploy-container.sh
sudo bash scripts/verify-container-deployment.sh

6. 重启 / 停止 / 删除容器

重启：

docker restart hw

停止：

docker stop hw

删除（下次需重新部署）：

docker rm -f hw

7. 回滚建议

当前仓库未内置自动回滚脚本，建议按以下原则手工回滚：

保留最近一个稳定版本代码目录或 git tag
回滚 /opt/hw 代码到稳定版本
重新执行：

cd /opt/hw
sudo bash scripts/deploy-container.sh
sudo bash scripts/verify-container-deployment.sh

如果本次发布包含数据库迁移：

优先评估迁移是否可逆
若不可逆，不要直接回滚旧代码后忽略数据库兼容性
生产环境务必先做数据库备份

8. 备份建议

8.1 MySQL

建议至少定期做：

mysqldump --single-transaction --quick --default-character-set=utf8mb4 -u <user> -p <database> > hw-backup.sql

8.2 SQLite（仅轻量环境）

停止容器后备份：

docker stop hw
cp /opt/hw/instance/happywedding.db /opt/hw/instance/happywedding.db.bak
docker start hw

9. 常见故障排查

9.1 容器启动失败

先看：

docker ps -a --filter name=hw
docker logs --tail 200 hw

优先检查：

/opt/hw.conf.d/hw.env 是否存在
HW_SECRET_KEY 是否仍是占位值
DATABASE_URL 是否为空或格式错误
/opt/hw/instance 是否可写
数据库是否可连通

9.2 校验脚本失败：端口未监听

说明容器没有在预期端口正常起来。检查：

docker logs --tail 200 hw
ss -tln | grep ':8000 '

如果宿主机没有 ss（例如部分 macOS 环境），可改用：

lsof -nP -iTCP:8000 -sTCP:LISTEN

9.3 `/health` 不通

可能原因：

容器未正常运行
容器内 Gunicorn 未起来
宿主机端口映射不正确
你实际发布的不是默认端口 8000

9.4 CSV 相关功能异常

优先检查目录权限：

/opt/hw/instance
/opt/hw/instance/csv_previews

它们需要对容器运行用户可写。

10. 安全提醒

生产环境不要使用默认 HW_SECRET_KEY
/opt/hw.conf.d/hw.env 应限制读取权限
如需对外暴露，请在容器前增加反向代理或防火墙规则，不建议裸暴露管理后台
当前项目仍建议在正式发布前补充 CSRF
如果宿主机是内网 / 离线环境，需要确保部署时 Docker 能成功构建镜像，或提前准备好基础镜像与依赖访问能力

11. 建议保留的最小操作清单

建议把以下命令记录到你的运维笔记中：

docker ps --filter name=hw
docker logs -f hw
docker restart hw
sudo bash /opt/hw/scripts/deploy-container.sh
sudo bash /opt/hw/scripts/verify-container-deployment.sh
curl -fsS http://127.0.0.1:8000/health

4.9 KiB Raw Permalink Blame History