# SiteForge 6.0.0 — 运维与安全说明

## 运行架构

- 单机 Compose：Web（认证及 API）、Worker（后台构建）、独立持久化数据卷、独立已发布文件卷；可选 Caddy HTTPS。
- 数据：SQLite WAL；一个站点同时间最多一个运行中的构建任务。长期多节点部署要替换存储和任务中心。
- 运行时只需公网暴露经正确配置的 HTTPS 反向代理。请不要把 8787 开放到公网。

## 日常排障

```bash
docker compose ps
docker compose logs --tail=100 siteforge
docker compose logs --tail=100 worker
docker compose exec siteforge python -c 'from app.version import VERSION;print(VERSION)'
```

正常时 `GET /api/health` 返回 `{"status":"ok","name":"SiteForge","version":"6.0.0"}`。Worker 未运行时 API 可以仍然健康，但构建会停留在 queued；因此应同时监测 Worker 容器。

## 数据安全

- 密钥只保存在 `.env` 或平台密钥管理器；生产 HTTPS 将 `SITEFORGE_COOKIE_SECURE=true`。
- 管理员密码至少 12 位，团队账号使用 scrypt 密码哈希；启用站点角色。
- 发布权限、迁移 SEO 阻断和审核不能仅由客户端判断，必须遵从后端校验。
- 不要任意加载第三方 Jinja/JS 主题代码；当前主题导入限制为声明式主题包。
- 旧站采集应只针对已获得授权的站点，防止内部网络 SSRF。

## 备份/恢复

SQLite 正在运行时不要直接只复制一个 `.sqlite3` 文件；应使用 SQLite 在线备份 API，并同步备份 media、theme_packages、archives、builds、legacy 及部署文件。可先停止维护性写入，再执行卷快照。恢复必须在空白测试部署上演练后才能用于正式生产。

## V5 升级

不要运行 `docker compose down -v`，不要覆盖 V5 的数据卷。使用全新 V6 Compose 名称和独立卷，检查账户、旧 URL/SEO、主题固定版本、素材、历史构建、发布根目录，再安排切换。

## Worker 任务处理

- 前端构建请求统一 HTTP 202 排队。
- `SITEFORGE_BUILD_TIMEOUT_SECONDS` 默认 300，可调整 10–3600 秒。
- `SITEFORGE_BUILD_MAX_ATTEMPTS` 默认 3，可调整 1–6。
- 用户取消排队任务立即 `cancelled`；运行中进入 `cancel_requested`，Worker 会终止构建子进程并确认状态。
- 临时任务错误才会指数退避重试；确定性数据错误标记 failed，避免无用重复尝试。
- Worker 领取任务后更新租约；租约过期可能重试任务。对于进程崩溃时未清理的孤儿进程，当前实现尚未保证多机严格一次执行，正式集群版需进程组隔离及分布式租约协议。