5.4 KiB
5.4 KiB
本地、生产服务器与远程仓库源码统一
| 字段 | 内容 |
|---|---|
| 状态 | Implemented |
| 级别 | S3 |
| 负责人 | Logan.Li |
| 创建日期 | 2026-08-05 |
| 最后更新 | 2026-08-05 |
| 关联任务 | 以 /srv/aiops 为主统一本地、服务器和 Git 远程仓库 |
1. 背景与证据
本地工作区位于 main@7a16808，服务器工作区位于 master@f22e575，两端分别与对应远程分支一致，但都有大量未提交改动。内容审计发现服务器有 131 个本地不存在的源码文件，本地有 12 个服务器不存在的近期工程文件，另有 39 个同路径文件内容不同。当前生产二进制包含部分本地独有后端能力，因此直接单向覆盖任一工作区都会造成代码或可复现性丢失。
2. 目标与非目标
目标
- 以服务器源码结构和行为为主形成唯一可构建源码。
- 保留本地独有且已验证或已进入生产二进制的功能，不丢失近期账单、迁移、数据保留和 CI 工程能力。
- 让远程
master与main、本地工作区和服务器源码指向同一提交。 - 保留变更前完整备份，并验证构建、测试、迁移和生产健康状态。
非目标
- 不提交生产
config.yaml、密钥、数据库、日志、备份、运行 PID 或历史二进制。 - 不在本次整理业务数据或执行数据库清理。
- 不改变生产运行参数和用户凭据。
3. 需求
功能需求
FR-01：统一提交必须包含服务器权威源码和本地独有的有效工程文件。FR-02：远程master与main必须最终解析到同一提交。FR-03：本地和服务器的受管源码必须与统一提交一致。FR-04：生产配置和运行数据必须保留在 Git 管理范围之外或保持未被覆盖。
非功能需求
NFR-01：任何覆盖、删除或分支更新前必须生成可验证备份。NFR-02：统一源码必须通过后端、前端和 Agent 的最低构建门禁。NFR-03：生产服务切换后/version、迁移状态、进程和错误日志必须正常。
4. 设计与边界
从 origin/master 创建独立 Git worktree。将服务器源码复制到该工作区，排除 .git、数据库、配置密钥、日志、缓存、备份、构建产物和历史二进制；再合并本地独有功能文件与本规格。测试通过后创建单一整合提交，并以普通快进或带租约保护的方式更新远程分支。
本地与服务器现有工作区在对齐前分别归档。对齐时仅重置受 Git 管理的源码；生产 config.yaml、数据库、日志、备份和运行文件保持不变。
5. 风险与可观测性
| 风险/失败模式 | 防护或降级 | 观测信号 |
|---|---|---|
| 服务器重构覆盖本地功能 | 隔离合并并保留本地独有文件，构建测试后才提交 | Git diff、测试结果 |
| 误提交生产密钥或数据 | 明确排除运行配置、数据库、日志和备份，并审计提交文件 | git status、提交清单 |
| 两个远程分支历史不同 | 先保存 bundle，再统一到经过验证的整合提交 | git ls-remote |
| 生产源码与二进制不一致 | 用统一源码重建 Linux 二进制并核对版本 | /version、二进制 SHA-256 |
6. 验收标准
AC-01：给定统一提交，origin/master与origin/main返回相同提交哈希。AC-02：给定统一提交，本地和服务器受管源码执行内容校验时没有差异。AC-03：统一源码通过 Go 后端、Agent、TypeScript、ESLint 和生产前端构建检查。AC-04：生产服务使用统一源码构建的 Linux 二进制启动，/version、迁移状态和日志正常。AC-05：生产配置、数据库、日志和备份未进入提交且未被覆盖。
7. 验证追踪
| 验收标准 | 测试或检查 | 结果 |
|---|---|---|
| AC-01 | git ls-remote origin refs/heads/main refs/heads/master |
Pass（两分支同一提交） |
| AC-02 | 本地与服务器 HEAD、受管源码状态和未跟踪文件审计 | Pass（仅保留生产运行配置与备份） |
| AC-03 | go test/go vet/go build、tsc -b、ESLint、Vite build、Agent build |
Pass（2026-08-05） |
| AC-04 | Linux 构建、/version、migrate status、进程和日志检查 |
Pass（迁移 0000-0003 均 applied） |
| AC-05 | 提交文件审计与生产文件哈希/存在性检查 | Pass（配置哈希和数据库大小保持一致） |
8. 发布与回滚
发布前保存本地和服务器源码归档、Git bundle、生产二进制及数据库现有备份。若统一源码验证失败，不更新远程分支或现有工作区。若生产切换失败，恢复上一二进制并保留统一提交供离线修复。远程分支更新使用预期旧哈希或 --force-with-lease 防止覆盖并发提交。
9. 决策记录
| 日期 | 决策 | 原因与影响 |
|---|---|---|
| 2026-08-05 | 服务器源码为结构基线，本地独有有效能力采用合并而非删除 | 服务器包含较新的组件拆分，本地包含当前生产二进制所需的新能力 |
| 2026-08-05 | 生产配置与运行数据不纳入源码一致性 | 防止泄密和破坏运行环境 |
| 2026-08-05 | main 与 master 同时快进到统一提交 |
保留两条历史且不需要强制推送 |
10. 遗留事项
- 后续开发统一使用主分支并通过提交同步，禁止在生产工作区形成长期未提交源码改动。