chore(spec): 创建 add-blog-infra 任务包(Phase 0 地基七任务)

- T1 备份 / T2 翻译引擎 / T3 gitea / T4 Artalk / T5 域名接入 / T6 发布链 / T7 验收
- 每任务 boundary+verify;nginx 集成仅 orchestrator,worker 交草稿
- 集成分支 spec/2026-10-24_add-blog-infra
This commit is contained in:
wait4x committed 2026-10-24 21:50:44 +08:00
1 parent 9a61e69f2f
commit 72025b7a43
2 files changed
+130

No files matched your search

@@ -0,0 +1,78 @@
# 博客重基建 Phase 0:备份/gitea/Artalk/发布链地基 - 项目范围
<!-- spec-format: 2 -->
## 1. 问题定义
- **项目目标**:为博客重建(详见 docs/博客重设计调研报告.md v1.8)铺好基础设施:生产数据备份、gitea 代码托管(双写作流后端)、Artalk 评论服务、域名接入与发布链地基;全程生产博客(Halo 18090)零影响
- **目标用户**:站长本人(后续 Phase 1-4 的构建/发布/翻译管线都跑在这套地基上)
- **核心价值**:Phase 1 可直接开工;生产可秒级回滚的安全网(备份 + nginx 切换预案)
## 2. 假设与待确认
### 2.1 已确认事实
- TLS 证书为通配符(`wait4x.online` + `*.wait4x.online`,openssl 实测),git 子域零新增证书
- postgres 容器用户 `wait4x`,Halo 库名 `halo_db`(docker inspect 实测);Halo 数据目录 `~/docker_apps/halo/halo2`
- `127.0.0.1:3000` 已被 new-api 占用;13020/13030 端口空闲(ss 实测)
- nginx 已有 ESA 回源 snippet(`snippets/esa-origin-ssl.conf`,含回源鉴权 stage 计划)
- 现有评论数 0,评论系统切换零迁移成本
- 调研决策全部定稿(报告 v1.8 §7):C'' 架构 / Artalk / 分阶段照片管线 / 双语预译 / 多端红线
### 2.2 关键假设
- ESA 控制台添加子域需用户手动操作(本会话无 ESA API 凭据)
- gitea/gitea 与 artalk 官方 docker 镜像可直接拉取(经本机 clash 代理)
- gitea web UI 上传默认限制(单次 5 文件)可在 app.ini 调大,不影响本包验收
### 2.3 待确认问题
- [ ] git.wait4x.online 走 ESA 代理(复用回源鉴权+通配证书)还是 DNS 直连?→ 倾向 ESA
- [ ] gitea 首管理员用户名(默认 wait4x)?
- [ ] gitea SSH 本期不暴露(https-only),后续按需加 13022 → 默认是
### 2.4 可选解释与取舍
- Artalk 挂主域 `wait4x.online/artalk` 路径(零新增子域、评论与博客同源)优于独立子域(多一次 DNS+证书面)→ 选路径
- gitea 独立子域(完整应用、path 反代需 ROOT_URL 子路径配置、体验差)优于主域路径 → 选子域
### 2.5 已证伪路径
- 无(暂无证伪记录)
## 3. 功能范围
### 3.1 核心功能(MVP)
- [ ] T1 生产备份:pg_dump(halo_db) + halo2 目录归档,落 `~/backups/blog/`
- [ ] T2 翻译引擎确认:new-api 网关模型列表 + 一次真实调用留证
- [ ] T3 gitea 部署:容器 13020 + 卷 + 管理员 + blog 空仓;nginx conf 草稿(不安装)
- [ ] T4 Artalk 部署:容器 13030 + sqlite 卷 + 站点配置;nginx conf 草稿(不安装)
- [ ] T5 域名接入:用户 ESA 加 git.wait4x.online 后,orchestrator 安装 conf + reload + 公网验证
- [ ] T6 发布链地基:webhook 接收脚本骨架 + 构建目录 + 回滚预案文档
- [ ] T7 Phase 0 验收:全部 verify 复跑 + 生产 Halo 无恙复查 + 板房汇报
### 3.2 扩展功能
- gitea SSH(13022)、gitea 镜像仓、ESA 缓存策略调优(二期按需)
### 3.3 不在范围内
- Astro 站点本身(Phase 1)、内容迁移(Phase 2)、双语管线(Phase 3)、上线切换(Phase 4)
## 4. 最小实现路径
- 两个容器各自独立 compose 于 `~/docker_apps/<name>/`,不共用网络外露端口(仅 127.0.0.1 绑定,公网经 nginx)
- nginx 集成(conf 安装/reload)只由 orchestrator 执行;worker 只交草稿——多写者单点集成
- 暂不引入:watchdog 容器、gitea runner(Phase 4 再上构建)、redis
## 5. 技术决策
- 技术栈:docker compose + nginx;gitea/gitea:latest;artalk/artalk:latest
- 证据协议:evidence: runs(verify 命令由 scripts/spec_verify.py 真实执行并记录)
- 本轮允许改动:`~/docker_apps/{gitea,artalk}/`、`/etc/nginx/sites-available/`(仅 T5 且先草稿评审)、`~/backups/blog/`、本仓库 `.spec/` 与 `infra/` 文档
- 本轮不应触碰:halo-halo-1 容器、postgres-db 数据、`~/docker_apps/halo/`、现有 nginx vhost(除新增文件)、生产 DNS/ESA(仅用户操作)
- Git integration branch:`spec/2026-10-24_add-blog-infra`
### 5.1 验证策略
- 范围级别:package(每任务 verify 命令真实执行;T7 全量复跑)
## 6. 成功标准
1. 备份三件套存在且可校验(pg_restore --list 可读、tar 抽查、大小>0)
2. `curl -sf http://127.0.0.1:13020/api/v1/version` 返回 JSON;gitea 有管理员与 blog 仓
3. `curl -sf http://127.0.0.1:13030/api` 返回 JSON;artalk 站点配置含 wait4x.online
4. (T5 用户操作后)`curl -sf https://git.wait4x.online` 与 `https://wait4x.online/artalk` 公网 200
5. 生产复查:halo-halo-1 healthy + `curl -sf http://127.0.0.1:18090` 200(与本包开工前状态一致)
6. 所有 verify 命令由 spec_verify 真实执行且通过,证据入 runs.jsonl
## 7. 目录结构审计
- 仓库现状:`docs/`(调研)+ `design/`(样板)+ `.spec/`(本包)+ `.githooks/`。职责清晰无需重组;Phase 1 再引入 `src/`(Astro)。运行态与源码分离已由 .gitignore 保证(.mesh/.team/node_modules/dist 忽略)。