94 lines
5.4 KiB
Markdown
94 lines
5.4 KiB
Markdown
# 本地、生产服务器与远程仓库源码统一
|
||
|
||
| 字段 | 内容 |
|
||
|------|------|
|
||
| 状态 | 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. 遗留事项
|
||
|
||
- 后续开发统一使用主分支并通过提交同步，禁止在生产工作区形成长期未提交源码改动。
|