termi-blog/deploy/docker/TOHKA_DEPLOY_RUNBOOK.md

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

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

1. 准备文件

先复制配置模板：

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

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

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

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

3. 启动容器

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

查看状态：

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

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 后，记得重新：

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