# tohka 最终部署操作手册（config.yaml 版）

这份手册按“准备 -> 渲染配置 -> 启动 -> 接 Caddy -> 启 timers -> 验证”执行。

## 1. 准备文件

先复制配置模板：

```bash
cp deploy/docker/config.yaml.example deploy/docker/config.yaml
```

再按生产实际填写：

- 域名
- Postgres / Redis 地址
- JWT secret
- SMTP
- TinyAuth / Pocket ID 共享密钥
- 镜像 tag

主配置源是：

- `deploy/docker/config.yaml`

## 2. 渲染 `.env`

```bash
python deploy/scripts/render_compose_env.py \
  --input deploy/docker/config.yaml \
  --output deploy/docker/.env
```

如果只是想预览，不落盘：

```bash
python deploy/scripts/render_compose_env.py \
  --input deploy/docker/config.yaml \
  --stdout
```

## 3. 启动容器

```bash
docker compose \
  -f deploy/docker/compose.package.yml \
  -f deploy/docker/compose.tohka.override.yml \
  --env-file deploy/docker/.env up -d
```

查看状态：

```bash
docker compose \
  -f deploy/docker/compose.package.yml \
  -f deploy/docker/compose.tohka.override.yml \
  --env-file deploy/docker/.env ps
```

## 4. 接宿主机 Caddy

直接参考：

- `deploy/caddy/Caddyfile.tohka.production.example`

建议域名：

- `blog.init.cool`
- `admin.blog.init.cool`
- `api.blog.init.cool`

关键点：

- `admin.blog.init.cool` 整体挂 `import tinyauth`
- `admin.blog.init.cool/api/*` 转 backend 时带：
  - `X-Termi-Proxy-Secret {$TERMI_ADMIN_PROXY_SHARED_SECRET}`

## 5. 启用 systemd timers

```bash
sudo cp deploy/systemd/*.service /etc/systemd/system/
sudo cp deploy/systemd/*.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now termi-retry-deliveries.timer
sudo systemctl enable --now termi-weekly-digest.timer
sudo systemctl enable --now termi-monthly-digest.timer
sudo systemctl enable --now termi-backup-all.timer
sudo systemctl enable --now termi-backup-prune.timer
sudo systemctl enable --now termi-backup-offsite-sync.timer
```

## 6. 做首轮验证

至少检查：

- `http://127.0.0.1:5150/healthz`
- `http://127.0.0.1:4321/healthz`
- `http://127.0.0.1:4322/healthz`
- `https://admin.blog.init.cool` 能正常走 Pocket ID / TinyAuth 登录
- 订阅确认邮件能正常送达
- 测试通知 / 周报 / 月报能正常入队并送达

## 7. 上线后维护动作

每次改 `deploy/docker/config.yaml` 后，记得重新：

```bash
python deploy/scripts/render_compose_env.py \
  --input deploy/docker/config.yaml \
  --output deploy/docker/.env

docker compose \
  -f deploy/docker/compose.package.yml \
  -f deploy/docker/compose.tohka.override.yml \
  --env-file deploy/docker/.env up -d
```

## 8. 配套文档

- `deploy/docker/README.md`
- `deploy/docker/ARCHITECTURE.md`
- `deploy/docker/TOHKA_POCKET_ID.md`
- `deploy/systemd/GO_LIVE_CHECKLIST.md`
- `deploy/docker/BACKUP_AND_RECOVERY.md`