chore: 统一本地服务器与远程仓库源码
- 合并 main 与 master 历史并以服务器结构为基线 - 保留迁移、数据保留、AWS 账单与部署安全能力 - 建立 SDD 规格和 CI 验证闭环
This commit is contained in:
Logan.Li committed
commit
fd60361d93
460 files changed
+37492
-23871
No files matched your search
@@ -5,6 +5,51 @@
|
||||
|
||||
---
|
||||
|
||||
## 0. 规格驱动开发（SDD，强制）
|
||||
|
||||
本项目采用 **Specification-Driven Development**。对于会改变行为、接口、数据或运维方式的工作，规格不是完成后的说明，而是实现前的约束和验收依据。
|
||||
|
||||
权威规范与模板：
|
||||
|
||||
- 流程、分级、质量门禁：`docs/specs/README.md`
|
||||
- 新规格模板：`docs/specs/_template.md`
|
||||
|
||||
### 0.1 变更分级
|
||||
|
||||
| 级别 | 典型范围 | 规格要求 |
|
||||
|------|----------|----------|
|
||||
| S0 | 文案、注释、格式、无行为变化的机械修改 | 不创建规格文件，但必须验证受影响文件 |
|
||||
| S1 | 局部缺陷修复、内部重构、单模块小改动 | 在任务计划中写清问题、约束、验收标准 |
|
||||
| S2 | 新功能、跨模块流程、API/数据模型/配置变更 | 实现前必须创建或更新 `docs/specs/<domain>/<slug>.md` |
|
||||
| S3 | 认证授权、账单、安全、数据库迁移、数据清理、生产部署 | 按 S2 执行，并补充风险、兼容性、可观测性、发布与回滚方案 |
|
||||
|
||||
级别取最高影响，不以代码行数判断。用户已给出明确需求时可以直接形成规格并继续；只有缺失选择会显著改变结果或扩大权限时才暂停询问。
|
||||
|
||||
### 0.2 强制工作流
|
||||
|
||||
1. **Discover**：先读现有代码、接口、模型、测试和工作区差异，以证据确认当前行为。
|
||||
2. **Specify**：写清目标、非目标、行为规则、接口/数据契约、验收标准和风险；S2/S3 必须落盘。
|
||||
3. **Design**：确定最小实现边界、复用点、迁移和回滚路径，禁止把未决问题留给编码阶段猜测。
|
||||
4. **Implement**：按规格逐项实现；发现规格错误时先更新规格，再改代码，禁止静默偏离。
|
||||
5. **Verify**：每条验收标准必须映射到自动化测试、构建检查或明确的人工验证证据。
|
||||
6. **Deliver**：交付说明必须列出实现结果、验证证据、未覆盖项和剩余风险；S2/S3 同步更新规格状态。
|
||||
|
||||
### 0.3 不可绕过的门禁
|
||||
|
||||
- API 改动必须先明确请求、响应、错误码、权限和兼容策略，再同步前后端。
|
||||
- 数据库改动必须使用版本化幂等迁移，说明数据回填、旧版本兼容、备份和回滚；禁止用启动期 `AutoMigrate` 代替生产迁移。
|
||||
- 认证、审批、远程执行、账单和密钥相关变更必须包含权限边界、审计行为和失败路径。
|
||||
- 监控、Agent 上报、日志等高频数据必须定义保留期、容量影响和清理可观测性。
|
||||
- 金额必须明确原币、报告币、汇率来源和精度；时间必须明确时区、统计窗口和边界日期。
|
||||
- 新增行为必须有测试。无法自动化的验收项要记录原因、人工步骤和结果，不能用“已检查”代替证据。
|
||||
- 实现不得夹带规格外重构；发现必要的额外工作，应先补入规格的范围或后续事项。
|
||||
|
||||
### 0.4 完成定义（Definition of Done）
|
||||
|
||||
代码编译通过不等于完成。S1 及以上变更至少满足：规格/计划与实现一致、验收标准全部有证据、相关测试通过、错误与空状态可用、权限和兼容性已检查、文档已同步、发布与回滚可执行。任一项缺失时必须明确标记未完成，不得宣称任务已完成。
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目概述
|
||||
|
||||
**AIOps** 是一个企业级云原生智能运维平台，聚焦三大核心能力：
|
||||
@@ -20,8 +65,8 @@
|
||||
| 产物 | 技术 | 说明 |
|
||||
|------|------|------|
|
||||
| `frontend/` | React 19 + TypeScript + Vite | Web 控制台 |
|
||||
| `backend/` | Go 1.24 + Gin + GORM | HTTP API + WebSocket + 前端静态资源服务 |
|
||||
| `agent/` | Go 1.24（CGO_ENABLED=0） | 主机指标采集 + 远程任务执行 |
|
||||
| `backend/` | Go 1.25 + Gin + GORM | HTTP API + WebSocket + 前端静态资源服务 |
|
||||
| `agent/` | Go 1.22 模块（Go 1.25 工具链，CGO_ENABLED=0） | 主机指标采集 + 远程任务执行 |
|
||||
|
||||
### 1.2 默认账号（生产必须修改）
|
||||
|
||||
@@ -41,7 +86,7 @@
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `backend/go.mod` | 后端 Go 模块定义，模块名 `ezops`，Go 1.24.0 |
|
||||
| `backend/go.mod` | 后端 Go 模块定义，模块名 `ezops`，Go 1.25.0 |
|
||||
| `agent/go.mod` | Agent 独立模块，模块名 `ezops/agent`，Go 1.22（与后端共用 1.24 工具链） |
|
||||
| `frontend/package.json` | 前端 npm 依赖与脚本 |
|
||||
| `frontend/vite.config.ts` | Vite 配置：端口 5173，代理 `/api`、`/ws`、`/health`、`/version`、`/agent` 到 `localhost:8080` |
|
||||
@@ -60,7 +105,7 @@
|
||||
|
||||
### 2.2 后端
|
||||
|
||||
- **语言 / 版本**：Go 1.24+
|
||||
- **语言 / 版本**：Go 1.25+
|
||||
- **Web 框架**：Gin v1.9.1
|
||||
- **ORM**：GORM v1.30.0
|
||||
- **数据库**：SQLite（local 模式，开发本机）、MySQL 8.0（生产）、PostgreSQL（可选）
|
||||
@@ -91,7 +136,7 @@
|
||||
- **数据请求**：TanStack Query 5+
|
||||
- **路由**：React Router 7+
|
||||
- **图表**：Recharts
|
||||
- **图标**：Lucide React
|
||||
- **图标**：Lucide React（通用 UI）+ Simple Icons（技术品牌按需导入）
|
||||
- **编辑器**：CodeMirror 6（`@uiw/react-codemirror` + `@codemirror/lang-yaml`）
|
||||
- **终端**：xterm.js
|
||||
- **国际化**：i18next + react-i18next（中/英双语）
|
||||
@@ -361,7 +406,7 @@ go build -o aiops .
|
||||
3. **新增 handler 不直接绑 model**，使用独立 request struct。
|
||||
4. **GORM 指针字段必须解引用**后再使用（`*field`）。
|
||||
5. **Update handler 禁止复用 CreateRequest**，使用 `map[string]interface{}` 接收。
|
||||
6. **编译参数**：`unset http_proxy https_proxy && export GOPROXY=https://goproxy.cn,direct && GOTOOLCHAIN=local CGO_ENABLED=1 go build -o aiops .`
|
||||
6. **编译参数**：`unset http_proxy https_proxy && export GOPROXY=https://goproxy.cn,direct && GOTOOLCHAIN=auto CGO_ENABLED=1 go build -o aiops .`
|
||||
7. **GORM `First()` 连续查询会带上次 ID**，请用 `Take()` 代替。
|
||||
8. 文件名使用 `snake_case.go`；类型/方法 `PascalCase`；变量 `camelCase`。
|
||||
|
||||
@@ -373,6 +418,8 @@ go build -o aiops .
|
||||
4. **Token 双保险**：`useUserStore.getState().token || localStorage.getItem('token')`。
|
||||
5. ESLint 禁止显式 `any`（`@typescript-eslint/no-explicit-any: error`）。
|
||||
6. 组件文件 `PascalCase.tsx`；工具文件 `camelCase.ts`。
|
||||
7. 通用操作、状态和导航使用 `lucide-react`；云厂商、CI/CD、监控和中间件等产品实体使用 `TechnologyBrandIcon` 或 `CloudBrandIcon`。
|
||||
8. 技术品牌图标从 `simple-icons` 按需导入并随构建产物发布；禁止使用 CDN、远程图片 URL 或 `master` 分支资源。云厂商缺失图标使用仓库本地 SVG 或官方资源。
|
||||
|
||||
### 6.5 UI 设计原则
|
||||
|
||||
@@ -482,7 +529,7 @@ WebSocket 无法设置自定义 header → 后端 `JWTAuth` 支持 `?token=` que
|
||||
|
||||
| # | 陷阱 | 解决 |
|
||||
|---|------|------|
|
||||
| Go1 | `go build` 超时 | `unset proxy + GOPROXY=https://goproxy.cn,direct + GOTOOLCHAIN=local` |
|
||||
| Go1 | `go build` 超时 | `unset proxy + GOPROXY=https://goproxy.cn,direct + GOTOOLCHAIN=auto` |
|
||||
| Go2 | handler 不包裹 Response | 必须 `model.Response{Code:200, Data:...}` |
|
||||
| Go3 | GORM 指针字段 | `*field` 解引用后再用 |
|
||||
| Go4 | Update 复用 CreateRequest | 用 `map[string]interface{}` |
|
||||
|
||||
Reference in new issue
Block a user