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

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

## 1. 服务组成

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

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

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

2. 数据库
   - 推荐 MySQL
   - 连接串由 `/opt/hw.conf.d/hw.env` 中的 `DATABASE_URL` 控制

3. 宿主持久化目录
   - `/opt/hw/instance`
   - `/opt/hw/instance/csv_previews`

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

## 2. 日常查看命令

### 2.1 查看容器状态

```bash
docker ps --filter name=hw
```

### 2.2 查看容器日志

```bash
docker logs -f hw
```

查看最近 200 行：

```bash
docker logs --tail 200 hw
```

### 2.3 查看健康检查

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

### 2.4 查看健康检查接口

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

如你发布到了其他端口：

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

## 3. 常规发布流程

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

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

建议的发布后检查：

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

## 4. 首次初始化基础数据

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

```bash
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`，需要重新部署容器让其生效：

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

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

重启：

```bash
docker restart hw
```

停止：

```bash
docker stop hw
```

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

```bash
docker rm -f hw
```

## 7. 回滚建议

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

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

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

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

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

## 8. 备份建议

### 8.1 MySQL

建议至少定期做：

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

### 8.2 SQLite（仅轻量环境）

停止容器后备份：

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

## 9. 常见故障排查

### 9.1 容器启动失败

先看：

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

优先检查：

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

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

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

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

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

```bash
lsof -nP -iTCP:8000 -sTCP:LISTEN
```

### 9.3 `/health` 不通

可能原因：

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

### 9.4 CSV 相关功能异常

优先检查目录权限：

- `/opt/hw/instance`
- `/opt/hw/instance/csv_previews`

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

## 10. 安全提醒

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

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

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

```bash
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
```