feat: ship blog platform admin and deploy stack

deploy/docker/TOHKA_POCKET_ID.md

@@ -0,0 +1,154 @@
+# tohka 上接入 Pocket ID / TinyAuth / Caddy 的推荐做法
+
+这份文档记录当前项目在 `tohka` 上最推荐的后台保护方式：
+
+```text
+Browser
+  -> Host Caddy
+    -> TinyAuth
+      -> Pocket ID (OIDC)
+        -> admin nginx
+        -> backend /api
+```
+
+## 1. 目标
+
+实现这些效果：
+
+- `blog.init.cool` 对外公开，走 frontend SSR
+- `admin.blog.init.cool` 整体受保护
+- admin 页面和它访问的 `/api/*` 同域
+- backend 信任 TinyAuth 注入的登录身份
+- 即使 backend 端口误暴露，也额外要求一个共享密钥头，降低伪造 `Remote-User` 风险
+
+## 2. 推荐使用的 compose 方式
+
+基础 compose：
+
+- `deploy/docker/compose.package.yml`
+
+在 tohka 上再叠加这个 override：
+
+- `deploy/docker/compose.tohka.override.yml`
+
+部署主配置源建议使用：
+
+- `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
+```
+
+这个 override 会做三件事：
+
+1. `frontend / admin / backend` 只绑定到 `127.0.0.1`
+2. 默认打开 `TERMI_ADMIN_TRUST_PROXY_AUTH=true`
+3. 默认关闭 `TERMI_ADMIN_LOCAL_LOGIN_ENABLED`
+
+## 3. `config.yaml -> compose_env` 里最关键的变量
+
+至少补这些：
+
+现在推荐直接从下面这个模板开始：
+
+- `deploy/docker/config.yaml.example`
+
+然后复制成：
+
+- `deploy/docker/config.yaml`
+
+至少补这些：
+
+```yaml
+compose_env:
+  APP_BASE_URL: https://admin.blog.init.cool
+  PUBLIC_API_BASE_URL: https://api.blog.init.cool
+  ADMIN_API_BASE_URL: https://admin.blog.init.cool
+  ADMIN_FRONTEND_BASE_URL: https://blog.init.cool
+
+  TERMI_ADMIN_TRUST_PROXY_AUTH: true
+  TERMI_ADMIN_LOCAL_LOGIN_ENABLED: false
+  TERMI_ADMIN_PROXY_SHARED_SECRET: replace-with-a-long-random-secret
+```
+
+说明：
+
+- `APP_BASE_URL` 建议填后台正式地址，便于后端生成后台相关链接
+- `TERMI_ADMIN_PROXY_SHARED_SECRET` 是 backend 和 Caddy 之间约定的共享密钥
+- backend 现在会在代理 SSO 模式下检查 `X-Termi-Proxy-Secret`
+
+## 4. Caddy 侧应该怎么配
+
+直接参考：
+
+- `deploy/caddy/Caddyfile.tohka.example`
+- `deploy/caddy/Caddyfile.tohka.production.example`
+
+关键点是：admin 域名下 `/api/*` 反代到 backend 时要带上：
+
+```caddy
+header_up X-Termi-Proxy-Secret {$TERMI_ADMIN_PROXY_SHARED_SECRET}
+```
+
+这样 backend 才会接受代理注入的：
+
+- `Remote-User`
+- `Remote-Email`
+- `Remote-Groups`
+
+## 5. 为什么要加共享密钥头
+
+如果只看 `Remote-User` 这类头，而 backend 又被公网直接访问，
+理论上别人可以手工伪造请求头来冒充后台用户。
+
+现在的建议闭环是：
+
+- backend 端口只监听 `127.0.0.1`
+- admin 域名入口必须经过 TinyAuth / Pocket ID
+- backend 额外校验 `X-Termi-Proxy-Secret`
+
+这样会稳很多。
+
+## 6. 后台登录页现在的行为
+
+当前逻辑：
+
+- 如果 `TERMI_ADMIN_LOCAL_LOGIN_ENABLED=true`，仍可用本地账号密码兜底
+- 如果关闭本地登录，admin 登录页会提示“请从受保护入口进入，并重新检查会话”
+- backend 会优先读取代理身份头
+
+## 7. 建议的 tohka 落地顺序
+
+1. 在 tohka 的大 Caddyfile 里接入 `admin.blog.init.cool`
+2. 给 admin 域名启用 `import tinyauth`
+3. `/api/*` 同域转发到 `localhost:5150`
+4. 加上 `X-Termi-Proxy-Secret`
+5. 用 `compose.tohka.override.yml` 启动容器
+6. 打开 `https://admin.blog.init.cool`
+7. 在后台里确认当前 session 的 `auth_source=proxy`
+
+完整部署步骤可再配合：
+
+- `deploy/docker/TOHKA_DEPLOY_RUNBOOK.md`
+
+## 8. digest / retry / 备份建议一起启用
+
+上线时建议连同这些一起启用：
+
+- `deploy/systemd/termi-retry-deliveries.timer`
+- `deploy/systemd/termi-weekly-digest.timer`
+- `deploy/systemd/termi-monthly-digest.timer`
+- `deploy/systemd/termi-backup-all.timer`
+- `deploy/systemd/termi-backup-prune.timer`
+- `deploy/systemd/termi-backup-offsite-sync.timer`
+
+这样后台保护、通知投递、备份恢复三件事才算闭环。