目标：从 git clone 到第一次对话，需要编辑的文件 = 0；云平台点一个按钮就能部署。
| 里程碑 |
状态 |
完成日期 |
成果文档 |
主要提交 |
| R0 · 预研 |
✅ 完成 |
2026-09-18 |
R0-预研结论.md |
见下方「R0」 |
| M1 · 镜像自包含与配置入库 |
✅ 完成 |
2026-09-18 |
M1-成果与测试报告.md |
faa3891（合并）· 标签 v1.1.0-rc1 · 子任务 A B C D |
| M2 · 首启向导 |
✅ 完成 |
2026-09-18 |
M2-成果与测试报告.md |
1da85bc + 5fee548 · 标签 v1.1.0-rc2 · 截图 |
| M3 · 第一批模板（Zeabur / Sealos）+ 1Panel |
✅ 完成（模板就绪，未上架） |
2026-09-18 |
M3-成果与测试报告.md |
89cf929 + fda6c9f · 子任务 E · 1Panel · 不打新标签，模板钉 1.1.0-rc2 |
| M4 · 第二批平台（Railway / Coolify / Dokploy）+ 全面验收 + 发布 |
✅ 完成（方案就绪，五个平台都未上架） |
2026-09-18 |
M4-成果与测试报告.md |
2f93ed8 + a26a286 · 标签 v1.1.0 · 1Panel 已在 M3 提前做完 |
项目已收官 —— v1.1.0 已发布、里程碑已关闭、公告见 Discussions #26。
全项目总结（R0～M4 成果、实测数据汇总、偏离设计的决策、遗留待办）见 总结.md。
| 问题 |
结论 |
| 向导保存后怎么让 opencode 生效 |
PATCH /global/config（不是 PATCH /config，后者写的文件没人读）。端到端 7.4～7.9 秒 |
| 用户装的 SKILL 怎么让模型看见 |
opencode 原生 skills.urls + POST /skill/refresh，0.07 秒。不需要写 huntercode 插件 |
| 需要多大内存 |
空闲 1.17 GB，深度分析 + 全市场扫描并发峰值 1.27 GB。最低 2 GB、推荐 4 GB |
| 云平台新卷 opencode 写得进去吗 |
Docker 卷可以；K8s PVC 不行，Sealos 模板必须 fsGroup: 1001 |
| GHCR 能匿名拉吗 |
agentpit / fin-r1 都可以。api 与 web 目前只有 amd64，M1 补 arm64。国内平台未测 |
| 问题 |
结论 |
| 从零到 6 服务健康要改几个文件 |
0 个（git clone → docker compose up -d）。大模型仍需配置，图形化向导是 M2 |
| 默认 compose 里还有仓库挂载吗 |
一处都没有；build: 段也全部移到 docker-compose.dev.yml |
| 大模型换配置要重启吗 |
不用。apply_llm() 走 PATCH /global/config，实测端到端 9.2 秒 |
| 老部署升级会不会缺表 |
不会。api 启动时两阶段迁移（init_db() → 增量），演示站实测 23/23 补齐 |
| 老用户升级要做什么 |
跑一次 bash scripts/migrate-volumes.sh（把 user-skills/ data-packages/ 搬进新卷），否则装过的 SKILL 会从界面消失 |
| 未配置大模型时会发生什么 |
opencode 照常启动、绝不回落 OpenCode Zen；发消息 5 秒内收到中文的「大模型尚未配置」 |
| 镜像发布了吗 |
四个镜像 1.1.0-rc1 已发 amd64 + arm64，GHCR 匿名可拉（见成果文档第九节） |
| 演示站在跑哪份镜像 |
已从本地构建切到 GHCR 预构建 rc1，切换后会话 70→70 不丢、真实对话 13.16 秒命中工具 |
db/migrations 里 7 个文件一直在静默失败 —— 它们依赖的基础表由 init_db() 建，而 postgres 的 initdb 在 api 之前就跑了它们。0010 会让「手工补跑过迁移」的库升级后起不来 —— 演示站正是这种库，实测反证：修复前退出码 3、修复后 0。- 18 处硬编码把开源用户的数据发到我们自己的演示站网关 ——
LLM_BASE_URL 8 处 + ONE_API_BASE_URL 10 处，全部清掉。
| 问题 |
结论 |
| 从零到第一次对话要改几个文件 |
0 个。git clone → docker compose up -d → 浏览器里走完五步向导 |
| 怎么防止公网上被人抢先初始化 |
HUNTER_SETUP_TOKEN。设了就一律要(不管来源看起来是不是本机)、错 5 次锁 15 分钟 |
| 来源判断能信吗 |
有反代时能信(优先 X-Real-IP、XFF 取最右项);裸 compose 没有反代时仍可伪造 —— 演示站上实测复现过,只能靠口令 |
| 第 3 步测什么 |
连通 / 对话 / 工具调用三项,由 api 容器发出(和 opencode 走同一条网络路径),各显示真实耗时;测不通不让保存 |
| schema 清洗开关要自己猜吗 |
不用。脏 schema 被拒 → 用 llm-shim 同一份 schema_clean.py 清洗重试,通过就自动设为开 |
| 配完要重启容器吗 |
不用。实测 apply → 就绪 283 毫秒,两个容器的 StartedAt 前后完全一致 |
| 演示站会不会被弹向导 |
不会。.env 里配了大模型 = 锁定状态,should_run=false,向导只读展示 |
- 来源判断可被伪造 —— 演示站上
X-Forwarded-For: 127.0.0.1 就能进向导、拿到 env-check。
- 向导说配好了、第一条消息却回「大模型尚未配置」 —— 热生效是 mergeDeep,占位模型名留在清单里,前端继续拿它发消息。
- 模型名写错被报成「key 无效」 —— 网关回 403 +「无权使用模型」,先按状态码判会把人引到错误的方向。
- 全新安装校验不了平台 key ——
HUNTER_UPSTREAM_URL 兜底为空之后 URL 没有协议头,界面把原因说成「连不上服务器」。
| 问题 |
结论 |
| 三个模板能用了吗 |
三份模板 + 工具链都就绪，等价 compose 从空卷跑通全流程；但三个平台都没有账号，一次真实部署都没做、都没上架。README 本轮不加部署按钮 |
| 没有账号怎么验证 |
deploy/tools/template-to-compose.py 把模板机械翻译成等价 compose（同镜像、同环境变量、用平台自己的方式生成随机密钥、同卷、同依赖、同 init 规则），本机从空卷跑。人不能在中间改，测的就是模板本身 |
| 静态校验做到什么程度 |
24 项全过：Zeabur 官方 JSON Schema、Sealos 15 个 K8s 资源过 kubeconform -strict、1Panel 过官方 validate_app_package.py（零 error 零 warning） |
| 最值钱的一个发现 |
api 不设 LLM_SHIM_URL → 向导五步全绿、engine-ready 也是 true，但发消息永远没回复、日志里一条报错都没有。服务名不叫 llm-shim 的部署（Sealos / 1Panel / 真实 Zeabur）全中 |
Zeabur 的 ${PASSWORD} |
每个服务一个，不是每次引用一个。要四把不同的密钥只能借位到四个服务再 expose；借位落点要保证依赖图无环 |
| 云平台上密钥怎么共享 |
不能用共享卷（Zeabur 官方明说不支持）。改成模板生成 + 环境变量注入，api / web / opencode 三家必须同值 |
| opencode 的卷 |
K8s fsGroup: 1001 / Zeabur init chown / 1Panel init.sh —— 三个平台各一套，不做就 CrashLoop。1Panel 那次是实测反证出来的 |
| 资源建议变了吗 |
没变（2 核 2 GB 起 / 推荐 4 GB）。磁盘从「镜像约 3.4 GB」更正为实测 3.8 GB |
- boot.sh 误报「密钥重启后会变」 —— 密钥来自环境变量时这句一个字都不成立，云用户白白被吓一跳。
- 向导第 1 步把环境变量来的密钥报成「首启自动生成（hunter_secrets 卷）」 —— 判据恒为真，本地在
.env 里显式设了也报错。
- api 的
LLM_SHIM_URL 缺失 —— 见上表「最值钱的一个发现」。
| 问题 |
结论 |
| 第二批平台做了哪几个 |
Railway（控制台手工搭建清单 + 生成模板并发布的步骤）、Coolify / Dokploy（两份可整段粘贴的 compose）。1Panel 在 M3 已提前做完 |
| Railway 为什么没有模板文件 |
官方就没有这种东西 —— 流程是先在控制台把项目跑通，再 Settings → Generate Template from Project 反向生成 |
| 五个平台上架了吗 |
一个都没有，一次真实部署都没做（没有账号）。所以 README 里没有任何部署按钮，只有文档 |
| 全面回归测了什么 |
四条用户路径：老用户升级（v1.0.1→1.1.0）/ 本地全新（不建 .env，playwright 走完向导）/ 云平台模式（六个平台的等价 compose）/ 开发模式。全部通过 |
| 「升级时有新迁移能不能补跑」验到了吗 |
验到了（M3 说这条还没验）。v1.0.1 老库从来没有账本，待执行 23 个全部补齐，两阶段 0.70 秒 |
| 顺手发现的一个真实线上故障 |
v1.0.x 的 initdb 迁移会在第 7 个文件上整个中止（ON_ERROR_STOP=1 + 基础表还没建），0007～0021 一个都没跑 —— 升级前 GET /api/watchlist 是 HTTP 500，升级后 200 |
| 云平台上最容易炸的三件事 |
① 卷带 lost+found → 直接当 PGDATA 用 postgres 无限重启；② 卷不拷贝镜像内容（Docker 具名卷会拷）→ 挂到镜像有东西的路径上等于把它删了；③ 不编排启动顺序 → opencode 等 api 只等 3 秒就放弃，重新部署后配置静默失效 |
| arm64 |
四个镜像的多架构 manifest 存在且匿名可拉；真机未测（手上没有 arm64 机器） |
- 合规声明弹窗盖住首启向导 —— 全屏遮罩拦掉所有点击，新用户开箱第一屏不是向导。
弹窗本来就排除了
/setup，但路径是在挂载时判的，而用户是从 / 跳过去的。
- 向导第 4 步「免费开源数据源」承诺了它做不到的事 —— 那一项不写任何配置，
用户选完第一条对话就顶出红色的「无法拉取 行情」。
- 首次生成的密钥被说成「还没落进卷」 —— 其实紧接着就写回去了。
- 冷启后头几十秒，第 1 步必现一条黄色
ReadTimeout —— opencode 还在加载插件。
migrate-volumes.sh 给的指引本身是错的 —— 用 -p 起的栈认不出项目名；
末尾提示的那条 refresh 命令是 401，还被 curl -s 吞掉、看上去像成功了。