部署
本页说明 AgentHub Home 和文档站的公开部署边界。它刻意不写私有主机路径、SSH alias、回滚命令和 secret。
私有运维边界
公开文档可以描述构建产物、发布源 worktree、smoke-test 形状和公开 URL。具体主机 copy 路径、备份目录、回滚命令、凭据和服务器清单只属于私有 server workspace。
发布源
AgentHub Home 应从 TokenDance workspace 治理文档登记的 clean release worktree 构建和打包。不要从脏的默认 worktree 或旧设计预览 worktree 部署。
| 来源 | 要求 |
|---|---|
| Git 分支 | fast-forward 到要发布的 commit |
| Worktree | 除本次发布变更外保持 clean |
| Package lock | 除非做依赖工作，否则不变 |
| 静态产物 | 由 pnpm build 生成 |
| 发现文件 | 输出中包含 robots.txt、sitemap.xml 和 llms.txt |
产品部署状态
本页只说明 AgentHub Home 静态站部署。它不是 Hub Server、Edge Server、Web 工作台、Remote/Cloud Edge 或飞书/Lark Gateway 的公开生产部署手册。
| 组件 | 公开部署状态 | 公开规则 |
|---|---|---|
| AgentHub Home | 静态导出可公开部署 | 从登记的 release source 构建，然后 smoke-test 公开路由 |
| AgentHub Docs | 静态导出可公开部署 | 保持双语路由、metadata、搜索、sitemap 和 llms.txt 同步 |
| AgentHub Desktop | 本地预览 / 打包进行中 | 公开文档可以描述本地预览和 UI 证据，不写成生产 rollout |
| Local Edge | 本地预览 | 公开文档可以描述本地 health check 和 workspace policy，不写私有主机配置 |
| Hub Server | 进行中 | 公开文档描述架构和授权边界；生产细节留在私有文档 |
| Web 工作台 | 进行中 | 公开文档描述 Hub-backed 行为和缺失证据，不写成通用可用 |
| 飞书/Lark Gateway | 开发中 | 公开文档描述设置清单和 callback 规则；真实租户配置留在私有文档 |
| Remote/Cloud Edge | 开发中 | 在 device proof 和路由证据齐备前，公开文档只描述安全要求 |
如果读者想本地运行产品，请引导到 安装与本地环境 和 快速上手。如果运维需要生产细节，请使用私有 server workspace，不要把路径或命令复制进本仓库。
本地构建
在站点发布源中运行：
powershell
pnpm test
pnpm build
pnpm lint
预期证据：
- 测试通过，覆盖当前 docs registry 和搜索索引；
- 静态导出完成；
out/里包含双语首页和 docs 路由；- lint 没有新增错误。
静态导出检查
构建后检查生成文件：
powershell
# 构建产物检查；公开路由保持无后缀。
# Next static export 会生成 .html 文件和配套 route data 目录。
Test-Path .\out\zh\index.html
Test-Path .\out\en\index.html
Test-Path .\out\zh\docs\index.html
Test-Path .\out\en\docs\index.html
Test-Path .\out\zh\docs\product-status.html
Test-Path .\out\zh\docs\identity-login.html
Test-Path .\out\zh\docs\design-system.html
Test-Path .\out\zh\docs\deployment.html
Test-Path .\out\sitemap.xml
Test-Path .\out\llms.txt
线上 Smoke
部署后使用 cache-busting query：
| 路由 | 确认内容 |
|---|---|
/zh?v=<version> | 当前首页、没有旧 hero、mock 可见、TokenDance Blue |
/en?v=<version> | 英文首页，语言文案正确 |
/zh/docs?v=<version> | 文档正文、侧栏、搜索和 TOC 正常渲染 |
/zh/docs/product-status?v=<version> | 产品状态表格正常渲染为表格 |
/zh/docs/design-system?v=<version> | 设计规则和 token 正常渲染 |
/zh/docs/deployment?v=<version> | 部署边界提示正常渲染 |
/llms.txt?v=<version> | 新文档链接存在 |
/sitemap.xml?v=<version> | 新双语路由存在 |
发布证据模板
公开发布证据应保持紧凑、可重复：
Text
commit: <git-sha>
tag: <release-tag>
package: <公开安全的 package 名称，不写私有路径>
build: test / lint / build 结果
routes: /zh, /en, /zh/docs, /en/docs, changed deep docs routes
seo: robots.txt / sitemap.xml / llms.txt / manifest content type
visual: desktop + mobile 截图，或说明 visual QA 被什么阻塞
smoke: cache-busting live URL 和 body keyword
private state: 已更新 server workspace，不把私有路径复制到这里
如果某个字段缺失，就明确写 missing proof。不要用乐观发布口径代替缺失证据。
文档完整性门禁
每次公开 docs 变更都应在部署前回答这张清单：
| 检查 | 所需证据 |
|---|---|
| 双语页面一致 | 英文和中文 MDX 具有相同状态、边界和示例 |
| 导航 | sidebar、previous/next 和 TOC 包含新增或变更章节 |
| 搜索 | src/lib/search-index.ts 包含用户真正会搜索的词 |
| 发现入口 | llms.txt、sitemap 和公开路由 metadata 保持同步 |
| 公私分离 | 不含 secret、host inventory、SSH alias、web root、backup path 或 rollback command |
| 状态口径 | preview、in progress、in development 不写成已通用可用 |
| Changelog | 用绝对日期记录 docs 变更 |
缓存和旧页面排查
如果线上还显示旧 hero、旧 mock、文档正文缺失或导航过期：
- 确认本地 release worktree commit。
- 确认 package 是从这个 worktree 构建的。
- 确认已部署静态文件中包含目标路由。
- 用 cache-busting query 请求该路由。
- 检查
/zh、/en、/zh/docs和深层 docs 路由是否表现不一致。 - 再去私有运维文档里排查 web-tier cache 或部署复制问题。
部署记录规则
- 公开文档可以记录 package 文件名和 commit/tag，作为用户可见发布证据。
- 公开文档不能写 live filesystem path、server user、SSH alias、backup path 或 rollback command。
- 如果部署被凭据或私有服务器访问阻塞，只能说站点构建就绪但尚未部署。
- 线上 smoke 通过后，再更新私有 server workspace 的 operations state。