CyberStrikeAI/docs/zh-CN/release-process.md

发布流程

本文用于维护者或部署者发布、升级和回滚 CyberStrikeAI。

版本准备

发布前检查：

• README.md 和 README_CN.md 的功能说明是否更新。
• docs/ 是否补充新功能文档。
• config.yaml 示例是否包含新增配置。
• OpenAPI 是否包含新增接口。
• 中英文 i18n 是否同步。
• 高风险功能是否有安全说明。

测试

至少运行：

go test ./internal/...

如果修改了入口、构建或命令：

go test ./cmd/...
go build -o cyberstrike-ai ./cmd/server

如果修改前端，手动验证：

• 登录。
• 对话流式输出。
• 设置保存和应用。
• 工具列表。
• 相关页面无控制台错误。

构建

go build -o cyberstrike-ai ./cmd/server

发布包应包含：

• cyberstrike-ai
• web/templates/
• web/static/
• config.yaml 示例。
• tools/
• roles/
• skills/
• agents/
• docs/
• README.md / README_CN.md
• LICENSE

不要把本地 data/、真实 config.yaml 密钥、上传附件和日志打进公开发布包。

升级检查清单

升级前：

• 停服务。
• 备份 config.yaml。
• 备份 data/。
• 备份自定义 tools/roles/skills/agents/knowledge_base。
• 记录当前版本和启动方式。

升级后：

• 启动服务。
• 登录。
• 测试模型。
• 检查工具列表。
• 检查知识库状态。
• 检查外部 MCP。
• 检查 C2/WebShell 是否按预期启用或关闭。
• 查看日志和审计。

回滚

触发回滚的常见情况：

• 服务无法启动。
• 数据库迁移失败。
• 核心对话功能不可用。
• 高风险功能行为异常。

回滚步骤：

1. 停止新版本。
2. 恢复旧二进制或旧代码。
3. 恢复升级前 config.yaml。
4. 恢复升级前 data/。
5. 启动旧版本并验证。

如果新版已修改数据库结构，必须恢复数据库备份，不能只替换二进制。

Changelog 建议

每个版本记录：

• 新增功能。
• 行为变更。
• 配置变更。
• 数据库变更。
• 安全修复。
• 兼容性说明。
• 升级注意事项。

高风险模块的变更要单独标出，例如 C2、WebShell、终端、外部 MCP、HITL。

发布风险分级

改动	风险	必测
文档、图片	低	链接和渲染
前端页面	中	登录、页面状态、API 错误
Handler/API	中	OpenAPI、权限、错误码
配置结构	高	旧配置兼容、ApplyConfig
数据库结构	高	旧库迁移、回滚策略
Agent/MCP/HITL	高	工具调用、审批、流式中断
C2/WebShell/Terminal	极高	授权环境、审计、禁用开关

发布说明里要按风险级别提示用户，而不是只列功能点。

配置兼容策略

新增配置字段要遵循：

• 省略时有安全默认值。
• 旧配置能启动。
• 示例 config.yaml 有注释。
• Web 设置页不会把未知字段误删。
• 热应用和重启两种路径都验证。

如果新增字段默认开启高风险功能，应重新考虑默认值。

数据库变更策略

SQLite 迁移要考虑：

• 用户可能从很老版本直接升级。
• 迁移中断后再次启动是否幂等。
• 新字段是否允许空值。
• 索引是否会锁表太久。
• 是否需要数据回填。

发布说明必须写清楚“升级前备份 data/”。

Release 验收脚本思路

最小自动化：

go test ./internal/...
go test ./cmd/...
go build -o cyberstrike-ai ./cmd/server

手动冒烟：

登录 -> 模型测试 -> 新建对话 -> 工具列表 -> HITL -> 知识库 -> 外部 MCP -> 关闭/开启 C2

对高风险模块，宁可多做一个授权靶场测试，也不要只靠单测放行。