v1.1.0 发布 · 从 git clone 到第一次对话,需要编辑的文件 = 0

[hangeaiagent]

git clone → docker compose up -d → 打开浏览器走完五步向导 → 开始对话。
需要编辑的文件:0 个。

v1.1.0 把上手门槛这件事整个重做了一遍。下面分三段:新用户怎么开始、老用户升级要做什么、部署到云平台。

---

一、浏览器里的首启向导

git clone https://github.com/agentpit-io/hunter-community
cd hunter-community
docker compose up -d
# 打开 http://localhost:3100,按向导走完

没有第二步。 密钥首次启动自动生成、数据库迁移由 api 启动时自动执行、
六个服务全部走预构建镜像(amd64 + arm64)。大模型在浏览器里配。

第 1 步 · 环境自检

六个服务、迁移账本、密钥来源与强度、卷可写、访问方式,逐项列出并带真实耗时。

第 2 步 · 选大模型

内置 5 个预设,卡片上的工具调用命中率与耗时全部抄自 docs/model-testing/ 的实测结果并标注了实测日期;也可以填任意 OpenAI 兼容网关。

第 3 步 · 填 key 当场测

连通 / 对话 / 工具调用三项,由 api 容器发出(和 opencode 实际调用走同一条网络路径),各显示真实耗时。
测不通不让保存 —— 不会出现「向导说配好了、第一条消息却没反应」。
schema 清洗开关由检测结果自动决定,不用自己猜。

第 5 步 · 完成

热生效,不重启任何容器(本地实测 0.83 秒)。设置页 →「大模型」→「重新运行初始化向导」可随时换模型。

全部截图见 docs/screenshots/setup-wizard/。

---

二、从 v1.0.x 升级 · 只有两件事

git pull
docker compose pull && docker compose up -d
bash scripts/migrate-volumes.sh     # 装过 SKILL / 导入过数据包的必须跑一次

1. 跑一次 scripts/migrate-volumes.sh。 user-skills/ 与 data-packages/ 从 bind mount 改成了 api 自己的具名卷,
   不跑的话你在界面里装过的 SKILL 会从列表上消失(文件一个都没丢,只是容器看不到了)。
   用 docker compose -p <名> 起的栈加上 --project <名>。
2. 其余什么都不用改。 .env 保持原样;里面配了 LLM_BASE_URL / LLM_API_KEY / LLM_DEFAULT_MODEL 的实例,
   这三项仍然优先且在界面上显示为「已锁定」,向导不会被弹出来。缺的表和列在第一次启动时自动补齐,api 日志里逐个列出来。

⚠️ 不要改 JWT_SECRET —— 它派生了加密已存 key 的密钥,换掉会让所有已保存的 key 解不开、登录全部失效。

升级路径实测(v1.0.1 → 1.1.0,带真实数据的老库)

项	结果
up -d 到六服务健康	41.7 秒,.env 一个变量都没加
自动迁移	待执行 23 个全部补齐,两阶段 0.70 秒
会话 / 用户 / 各表行数	一条不丢,两条对话正文逐条全等
升级前签发的 token、加密存的 key	仍然有效、仍然解得开
向导	不出现(.env 锁定)

顺带修掉一个真实故障:v1.0.x 把 db/migrations 挂给 postgres 当 initdb 目录,而它在第 7 个文件处会因基础表还没建而整个中止 ——
0007 之后的迁移一个都没跑过。实测升级前 GET /api/watchlist 是 HTTP 500(缺列),升级后 200。

---

三、部署到云平台

五个平台各有一篇逐步说明:

平台	适合谁	文档
Zeabur	国内外都能用,能力最全	docs/deploy/zeabur.md
Sealos	国内用户	docs/deploy/sealos.md
Railway	海外用户	docs/deploy/railway.md
1Panel	自有服务器 + 国产面板	docs/deploy/1panel.md
Coolify / Dokploy	自有服务器 + 自托管 PaaS	docs/deploy/coolify-dokploy.md

说明白一件事:这一版没有「一键部署」按钮

我们没有这五个平台的任何账号,一次真实部署都没做过,也没有上架到任何一家的模板市场。
所以不放按钮,只给文档 —— 放一个点下去可能起不来的按钮,比不放更糟。

每份模板都做过等价验证:用 deploy/tools/template-to-compose.py 把模板机械翻译成 compose
(同镜像、同环境变量、用平台自己的方式生成的随机密钥、同卷、同依赖、同 init 规则),
在本机从空卷跑完「六服务健康 → 走完向导 → 真实对话 → 深度分析 → 重启数据不丢」。人不能在中间改。
各篇文档都写明了哪些验过、哪些没验过、平台上要自己核对什么。

有账号的朋友帮忙实测一次,欢迎来 Issues 说结果 —— 验过就加按钮。

公网部署必看

这些平台上的实例一创建就在公网上。每份模板都默认关掉了单用户免登录(HUNTER_SINGLE_USER=0)
并生成一道初始化口令 HUNTER_SETUP_TOKEN,向导第 0 步要填它 ——
不然谁先打开谁就能把大模型配成他自己的。口令在平台的环境变量面板里看。

---

四、这一轮顺带修掉的几个坑

• 合规声明弹窗盖住首启向导:新用户开箱第一屏本该是向导,却被一张全屏遮罩挡住「下一步」。
• 向导第 4 步「免费开源数据源」承诺了它做不到的事:选了它第一条对话就顶出红色的「无法拉取 行情」。文案已改成如实说明。
• 云部署时向导五步全绿、发消息却永远没有回复,日志里一条报错都没有(api 缺 LLM_SHIM_URL)。
• 重新部署之后向导里配好的模型又变回「尚未配置」:opencode 等 api 只等 3 秒,而云平台大多不编排启动顺序。
• scripts/migrate-volumes.sh 给的指引本身是错的:用 -p 起的栈认不出项目名;末尾提示的刷新命令是 401 还被 curl -s 吞掉、看上去像成功了。

完整清单见 CHANGELOG;
整个改造过程的实测数据与决策记录在 docs/setup-wizard/
(含全项目总结)。

---

资源建议

内存最低 2 GB、推荐 4 GB(实测空闲 587 MB、深度分析 + 全市场扫描并发峰值 1239 MB,opencode 一家占七成);
四个镜像合计 3.3 GB,加数据卷留 8 GB 以上;2 核起。

有问题来 Q&A,
想要什么功能去 Ideas 投票。