chore: 统一本地服务器与远程仓库源码

- 合并 main 与 master 历史并以服务器结构为基线
- 保留迁移、数据保留、AWS 账单与部署安全能力
- 建立 SDD 规格和 CI 验证闭环

docs/automation-deploy/README.md

@@ -25,6 +25,7 @@
 | 远程执行 | 已完成 | SSH 执行、上传、结果查看 |
 | Agent 任务 | 已完成 | Agent 轮询 command/script |
 | Pipeline | 已完成 | 流水线定义、阶段、执行日志 |
+| Jenkins 接入 | 已完成 | 保存 Jenkins API Token/密码、扫描 Jobs、同步为外部流水线、触发构建并回填日志 |
 | 发布管理 | 已完成 | 发布单、环境、审批、详情 |
 | Workspace 文件 | 已完成 | 构建目录文件浏览 |
 | Workspace 终端 | 已完成 | xterm 进入构建目录 |
@@ -42,6 +43,7 @@
 | 远程执行 | `remote_exec.go` | `RemoteExecPage.tsx` |
 | Agent 任务 | `agent_task.go` | Agent 监控相关页面 |
 | Pipeline | `pipeline*.go` | `PipelineManager.tsx`、`PipelineEditor.tsx` |
+| Jenkins 接入 | `pipeline_jenkins.go` | `JenkinsSettingsDialog.tsx`、`PipelineCard.tsx` |
 | 发布 | `pipeline_release.go`、`deploy*.go` | `ReleaseManager.tsx`、`AppRelease.tsx` |
 | Workspace | `workspace_files.go` | `FileBrowserDialog.tsx`、`WorkspaceTermDialog.tsx` |
 | 审批 | `approval*.go` | `ApprovalFlow.tsx` |
@@ -68,6 +70,41 @@ Backend
 
 ---
 
+## Pipeline 双模式
+
+AIOps 流水线支持两种执行模式，默认仍为平台原生执行，Jenkins 作为外部 CI Provider 接入：
+
+| 模式 | `ci_provider` | 适用场景 | 执行方式 |
+|------|---------------|----------|----------|
+| AIOps 原生 | `aiops` | 新项目、希望统一在平台内完成构建/发布/日志/Workspace | AIOps 调度构建节点，本地执行 stages，并写入 `deploy_pipeline_runs` |
+| Jenkins | `jenkins` | 企业已有 Jenkins Job，需要平滑纳管和统一审计 | AIOps 保存 Job 映射，调用 Jenkins API 触发构建，轮询状态与 console log |
+
+Jenkins 接入流程：
+
+1. 在流水线页面点击 `Jenkins`，填写 Jenkins 地址、用户、API Token 或密码。
+2. 后端使用 `crumbIssuer/api/json` 自动获取 CSRF crumb。
+3. 通过 `/api/json` 递归扫描 Folder/Job，按 Job URL 去重。
+4. 同步到 `deploy_pipelines`，设置 `ci_provider=jenkins`、`jenkins_job_name`、`jenkins_job_url`。
+5. 用户触发 Jenkins 类型流水线时，AIOps 按全局引用策略展示分支、Tag 或二者，并调用 `build` 或 `buildWithParameters`。
+6. Jenkins 返回队列地址后，AIOps 轮询 queue/build API，并通过 `logText/progressiveText` 增量读取 console log，按行写入 `deploy_pipeline_runs`。
+
+触发参数约定：
+
+- Jenkins 全局配置提供 `ref_mode` 和 `ref_param`。`ref_mode=branch` 只展示分支，`tag` 只展示 Tag，`both` 允许用户二选一。// Logan.Li
+- AIOps 不修改 Jenkins Job 配置，Job 的 Git 参数、Choice 参数、Shell 构建步骤仍以 Jenkins 为准；同步时只读保存参数定义、Git URL 和 Shell 摘要。// Logan.Li
+- 用户触发 Jenkins Job 时，前端按 Jenkins 实际参数定义渲染表单；GitParameter 会优先通过同步到的 Git URL 只读拉取分支或 Tag 候选。
+- 用户选择 Tag 或 Branch 时，写入 Jenkins Job 实际参数名；若 Job 未返回参数名，则回退到全局 `ref_param`，默认参数名为 `SELECT`。
+- 前端/接口传入 `variables` 时，会作为 Jenkins build parameters 一并发送。
+- Jenkins 未启用或 Token 不可用时，只影响 Jenkins 类型流水线，不影响 AIOps 原生流水线。
+
+安全约定：
+
+- Jenkins Token/密码只加密落库，不通过 GET 接口回显。
+- 列表只展示 `token_set`，前端留空保存时保留旧密钥。
+- Job 同步只保存 Job 元信息，不保存 Jenkins 构建参数里的敏感值。
+
+---
+
 ## 日志与输出
 
 | 类型 | 存储/通道 | 说明 |

docs/database-migrations.md

@@ -0,0 +1,41 @@
+# 数据库版本化迁移
+
+服务进程启动时**不会**执行数据库结构变更。数据库升级必须在备份成功、单实例维护窗口内显式运行迁移命令，避免大 SQLite 库发生隐式重建和 WAL 写放大。 // Logan.Li
+
+## 日常命令
+
+```bash
+# 查看已应用与待执行版本
+./aiops migrate status --config /srv/aiops/config.yaml
+
+# 全新空数据库：创建初始基线并执行后续迁移
+./aiops migrate up --config /srv/aiops/config.yaml
+
+# 已存在的旧数据库：人工核验、备份完成后，只写入基线记录，不改业务表
+./aiops migrate baseline --config /srv/aiops/config.yaml
+
+# 旧库完成 baseline 后，执行后续待迁移版本
+./aiops migrate up --config /srv/aiops/config.yaml
+```
+
+`baseline` 会校验 `iam_users`、`iam_roles`、`asset_servers`、`deploy_pipelines`、`monitor_agent_reports` 等核心表；校验失败时拒绝登记，不能用它绕过不完整库的恢复或专项迁移。 // Logan.Li
+
+## 已上线数据库的切换步骤
+
+1. 停止写入或切换至维护窗口，并完成可恢复备份。
+2. 运行 `aiops migrate status`，确认已有 `0001_agent_credentials` 记录仍然存在。
+3. 运行 `aiops migrate baseline`，它只登记 `0000_baseline_schema`。
+4. 再运行 `aiops migrate up`；`0002_legacy_schema_patches` 会把既有的兼容字段补丁作为可审计迁移执行。
+5. 再次运行 `status`，确认所有版本均为 `applied`，然后启动服务。
+
+线上已存在的 `sys_schema_migrations(version, applied_at)` 表保持兼容：迁移框架不会假设额外列，也不会重写既有 `0001_agent_credentials` 记录。 // Logan.Li
+
+若旧业务库甚至尚无 `sys_schema_migrations`，`migrate up` 会零写入拒绝；只能由维护人员先完成备份并显式执行 `migrate baseline`。 // Logan.Li
+
+## 新迁移规则
+
+- 新版本只追加到 `backend/migrations/` 和 `migrations.All()`，禁止修改或重命名已发布版本。
+- 需要方言差异的 SQL 使用 `<version>.<sqlite|mysql|postgres>.sql` 三份脚本。
+- 复杂或需调用 GORM 的变更使用 Go 迁移函数，但必须返回错误；禁止吞掉 DDL/DML 错误。
+- MySQL DDL 可能隐式提交，执行迁移前必须备份；同一数据库同一时间只能运行一个迁移进程。
+- SQLite 大表迁移与 `VACUUM` 必须在停写维护窗口执行，迁移完成后再进行 WAL checkpoint 与空间核验。

docs/database-schema.md

@@ -0,0 +1,201 @@
+# 数据库设计
+
+## 概述
+
+AIOps 使用 GORM 作为 ORM 框架，支持 SQLite / MySQL / PostgreSQL。
+
+- **默认**: SQLite（零配置，数据文件 `backend/data/aiops.db`）
+- **生产**: 推荐使用 MySQL 或 PostgreSQL
+
+首次初始化请显式执行 `aiops migrate up` 创建基线；服务启动时不会自动修改表结构。迁移流程见 [数据库版本化迁移](../database-migrations.md)。 // Logan.Li
+
+## 数据模型
+
+### 用户体系
+
+#### users - 用户表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| username | string | 用户名（唯一） |
+| password | string | 密码（bcrypt 加密） |
+| email | string | 邮箱 |
+| phone | string | 手机号 |
+| real_name | string | 真实姓名 |
+| avatar | string | 头像 URL |
+| status | int | 状态（1=正常 0=禁用） |
+| last_login | time | 最后登录时间 |
+| created_at | time | 创建时间 |
+| updated_at | time | 更新时间 |
+
+#### roles - 角色表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| name | string | 角色名称 |
+| code | string | 角色代码 |
+| description | string | 角色描述 |
+| sort | int | 排序 |
+
+#### permissions - 权限表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| name | string | 权限名称 |
+| code | string | 权限代码 |
+| type | string | 权限类型（menu/btn/api） |
+| path | string | 路由路径 |
+| method | string | HTTP 方法 |
+
+### 服务器管理
+
+#### servers - 服务器表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| name | string | 服务器名称 |
+| hostname | string | 主机名 |
+| ip | string | IP 地址 |
+| port | int | SSH 端口 |
+| os | string | 操作系统 |
+| cpu | int | CPU 核数 |
+| memory | int64 | 内存（MB） |
+| disk | int64 | 磁盘（GB） |
+| status | string | 状态（online/offline/maintenance） |
+| tags | string | 标签（JSON） |
+| cloud_id | uint | 关联云账号 |
+| region | string | 地域 |
+
+#### clouds - 云平台表
+#### cloud_accounts - 云账号表
+#### regions - 地域表
+#### domains - 域名表
+
+### K8s 管理
+
+#### k8s_clusters - K8s 集群表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| name | string | 集群名称 |
+| version | string | K8s 版本 |
+| api_server | string | API Server 地址 |
+| kubeconfig | string | Kubeconfig 内容 |
+| status | string | 集群状态 |
+
+#### k8s_nodes, k8s_pods, k8s_deployments, k8s_services, k8s_ingresses
+
+### 监控告警
+
+#### alert_rules - 告警规则表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| name | string | 规则名称 |
+| description | string | 规则描述 |
+| type | string | 告警类型 |
+| source | string | 数据源 |
+| expression | string | PromQL 表达式 |
+| severity | string | 严重级别（critical/warning/info） |
+| duration | string | 持续时间 |
+| notify_channels | string | 通知渠道（JSON） |
+| enabled | bool | 是否启用 |
+
+#### alert_events - 告警事件表
+#### notify_channels - 通知渠道表
+#### metric_data - 指标数据表
+
+### CI/CD
+
+#### pipelines - 流水线表
+#### pipeline_runs - 流水线执行记录表
+#### app_releases - 应用发布表
+
+### 自动化运维
+
+#### cron_jobs - 定时任务表
+#### scripts - 脚本表
+#### task_executions - 任务执行记录表
+#### playbooks - Ansible Playbook 表
+
+### 审批流程
+
+#### approval_templates - 审批模板表
+#### approval_processes - 审批流程表
+#### approval_steps - 审批步骤表
+
+### 其他
+
+#### navigation_groups - 导航分组表
+#### navigation_links - 导航链接表
+#### audit_logs - 审计日志表
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | uint | 主键 |
+| user_id | *uint | 操作用户 ID |
+| module | string | 模块 |
+| action | string | 操作类型 |
+| resource | string | 资源标识 |
+| request | string | 请求内容 |
+| response | string | 响应内容 |
+| error | string | 错误信息 |
+| ip | string | 操作 IP |
+| created_at | time | 操作时间 |
+
+## 表关系
+
+```
+users ──< user_roles >── roles ──< role_permissions >── permissions
+
+servers ──> cloud_accounts ──> clouds
+servers ──> regions
+
+alert_rules ──< alert_events
+alert_rules ──> notify_channels
+
+pipelines ──< pipeline_runs
+app_releases ──> pipelines
+
+approval_templates ──< approval_processes ──< approval_steps
+
+navigation_groups ──< navigation_links
+```
+
+## 版本化迁移
+
+模型基线由 `backend/pkg/database/database.go` 的 `BootstrapSchema` 定义，但只允许由 `aiops migrate up` 显式调用。后续变更按版本存放在 `backend/migrations/`，并记录至 `sys_schema_migrations`；已运行的服务不会在启动期间执行迁移。 // Logan.Li
+
+## 切换数据库
+
+### MySQL
+
+编辑 `backend/config.yaml`：
+```yaml
+database:
+  driver: mysql
+  host: localhost
+  port: 3306
+  user: root
+  password: your_password
+  dbname: aiops
+  charset: utf8mb4
+```
+
+### PostgreSQL
+
+```yaml
+database:
+  driver: postgres
+  host: localhost
+  port: 5432
+  user: postgres
+  password: your_password
+  dbname: aiops
+```

docs/db-table-audit.md

@@ -0,0 +1,412 @@
+# 数据表与菜单域审计记录
+
+> 审计范围：`backend/model`、`backend/pkg/database/database.go`、主要 controller/service/repository 引用、`backend/seed/seed.go` 默认菜单权限。
+> 目标：按菜单域整理表清单，记录表名前缀、设计合理性、疑似旧表/无用表和后续整改建议。
+
+## 重建版目标设计
+
+测试环境允许直接重建时，建议采用 **Schema v2 全局统一方案**：按菜单域和平台基础域重新归类，旧表不做兼容 rename，直接调整 `TableName()`、AutoMigrate 清单、种子数据和相关查询引用，然后清空数据库重建。
+
+### 全局命名原则
+
+1. 表名统一使用：`<domain>_<resource_plural>`。
+2. 领域前缀与菜单域保持一致，避免同一功能散落在 `sys_`、`ops_`、`monitor_`。
+3. 关联表统一使用：`<left_domain>_<left>_<right>` 或同域 `<domain>_<left>_<right>`。
+4. 配置类表可用单数语义但表名仍用复数，例如 `deploy_build_master_configs`。
+5. 时序/日志大表必须明确后缀：`*_samples`、`*_histories`、`*_events`、`*_logs`。
+6. 不再新增无前缀表。
+
+### 目标前缀
+
+| 前缀 | 菜单/领域 | 说明 |
+| --- | --- | --- |
+| `iam_` | 身份与权限 | 用户、角色、权限、凭据、LDAP、资源级授权 |
+| `sys_` | 系统基础配置 | 系统任务、站内导航、全局配置 |
+| `audit_` | 安全审计 | 操作审计、登录日志、终端/RDP 会话、命令审计 |
+| `asset_` | 资产/云资源 | 服务器、云账号、云区域、域名、账单、资源型号 |
+| `k8s_` | Kubernetes | 集群与同步缓存资源 |
+| `deploy_` | 应用发布 | 流水线、运行记录、发布、环境、构建节点、工具 |
+| `monitor_` | 监控告警 | 告警、指标、Agent、SNMP、站点拨测、中间件、数据源 |
+| `ops_` | 自动化运维 | 定时任务、脚本、远程执行、Ansible 如保留 |
+| `approval_` | 资源申请/审批 | 模板、流程、实例、步骤 |
+| `ai_` | AIOps/AI | LLM、会话、分析轨迹、Agent CLI 运行记录 |
+
+### 目标表清单
+
+#### IAM / 系统基础
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `iam_users` | 保留 |
+| `iam_roles` | 保留 |
+| `iam_permissions` | 保留 |
+| `iam_user_roles` | 保留 |
+| `iam_role_permissions` | 替换 `role_permissions` |
+| `iam_credentials` | 保留，作为全局凭据唯一主表 |
+| `iam_ldap_configs` | 保留 |
+| `iam_item_roles` | 保留 |
+| `iam_user_item_roles` | 保留 |
+| `iam_log_scope_roles` | 从 `monitor_log_scope_roles` 调整，日志查询权限本质是权限控制 |
+| `iam_user_log_scope_roles` | 从 `monitor_user_log_scope_roles` 调整 |
+| `sys_system_task_statuses` | 从 `sys_system_task_status` 调整为复数 |
+| `sys_navigation_groups` | 保留 |
+| `sys_navigation_links` | 替换 `navigation_links` |
+
+#### 安全审计
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `audit_operation_logs` | 替换 `sys_audit_logs` |
+| `audit_settings` | 替换 `sys_audit_settings` |
+| `audit_login_logs` | 替换 `sys_login_logs` |
+| `audit_terminal_sessions` | 替换 `sys_terminal_sessions` |
+| `audit_rdp_sessions` | 替换 `sys_rdp_sessions` |
+| `audit_session_commands` | 替换 `sys_session_commands` |
+
+#### 资产 / 云资源
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `asset_servers` | 保留 |
+| `asset_host_groups` | 保留 |
+| `asset_cloud_platforms` | 替换 `asset_clouds` |
+| `asset_cloud_accounts` | 保留，敏感字段统一转凭据 ID |
+| `asset_cloud_regions` | 替换 `asset_regions` |
+| `asset_domains` | 保留 |
+| `asset_resource_models` | 保留 |
+| `asset_cloud_billing_records` | 替换 `asset_cloud_billings`，语义更明确 |
+| `asset_cloud_billing_alert_rules` | 替换 `monitor_billing_alert_rules`，账单告警属于资产账单域配置，触发事件再进监控事件 |
+
+#### Kubernetes
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `k8s_clusters` | 替换 `kubernetes_clusters` |
+| `k8s_nodes` | 替换 `kubernetes_nodes` |
+| `k8s_pods` | 替换 `kubernetes_pods` |
+| `k8s_deployments` | 替换 `kubernetes_deployments` |
+| `k8s_services` | 替换 `kubernetes_services` |
+| `k8s_ingresses` | 替换 `kubernetes_ingresses` |
+| `k8s_topology_layouts` | 替换 `kubernetes_topology_layouts` |
+
+#### 应用发布
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `deploy_pipelines` | 替换 `ops_pipelines` |
+| `deploy_pipeline_runs` | 替换 `ops_pipeline_runs` |
+| `deploy_app_releases` | 保留 |
+| `deploy_environments` | 保留 |
+| `deploy_build_nodes` | 保留 |
+| `deploy_build_master_configs` | 替换 `deploy_build_master_config` |
+| `deploy_pipeline_members` | 保留 |
+| `deploy_user_groups` | 保留 |
+| `deploy_user_group_members` | 保留 |
+| `deploy_tools` | 保留 |
+| 已删除 `deploy_pipeline_repos` | 发布配置直接使用 `iam_credentials` + Pipeline 凭据字段 |
+| 已删除 `deploy_pipeline_registries` | 发布配置直接使用 `iam_credentials` + Pipeline 凭据字段 |
+
+#### 监控告警
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `monitor_targets` | 保留 |
+| `monitor_metrics` | 保留，作为指标定义表 |
+| `monitor_metric_samples` | 合并/替换 `metric_values` 和 `monitor_metric_histories` |
+| `monitor_metric_aggregates` | 替换 `monitor_metrics_aggregate` |
+| `monitor_metric_tags` | 保留 |
+| `monitor_alert_rules` | 保留但只保留一个模型定义 |
+| `monitor_alert_conditions` | 保留 |
+| `monitor_alert_events` | 保留 |
+| `monitor_alert_channels` | 替换 `monitor_notify_channels` |
+| `monitor_alert_contacts` | 保留 |
+| `monitor_alert_contact_groups` | 保留 |
+| `monitor_alert_notify_policies` | 保留 |
+| `monitor_alert_notify_templates` | 保留 |
+| `monitor_alert_notify_settings` | 保留 |
+| `monitor_alert_upgrades` | 保留 |
+| `monitor_alert_upgrade_records` | 保留 |
+| `monitor_alert_silences` | 保留 |
+| `monitor_agent_reports` | 保留 |
+| `monitor_agent_tasks` | 保留 |
+| `monitor_agent_rules` | 保留 |
+| `monitor_agent_alerts` | 保留 |
+| `monitor_agent_port_policies` | 替换 `monitor_agent_port_policy`，并加入迁移 |
+| `monitor_health_probes` | 保留 |
+| `monitor_prometheus_datasources` | 保留 |
+| `monitor_zabbix_datasources` | 保留 |
+| `monitor_log_datasources` | 保留 |
+| `monitor_trace_datasources` | 保留 |
+| `monitor_site_tasks` | 替换 `ops_site_tasks` |
+| `monitor_site_results` | 替换 `ops_site_results` |
+| `monitor_site_alerts` | 替换 `ops_site_alerts` |
+| `monitor_snmp_devices` | 替换 `ops_snmp_devices` |
+| `monitor_snmp_templates` | 替换 `ops_snmp_templates` |
+| `monitor_snmp_template_oids` | 替换 `ops_snmp_template_oids` |
+| `monitor_snmp_samples` | 替换 `ops_snmp_metrics`，删除 `snmp_history` |
+| `monitor_snmp_interfaces` | 替换 `ops_snmp_interfaces` |
+| `monitor_dashboards` | 保留一个大屏主表 |
+| `monitor_dashboard_panels` | 替换 `dashboard_panels` |
+| 已删除 `monitor_custom_dashboards` | 合并到 `monitor_dashboards`，用 `type/custom` 区分 |
+| 删除 `monitor_metric_data` | 用 `monitor_metrics` 替代 |
+
+#### 自动化运维
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `ops_cron_jobs` | 保留 |
+| `ops_scripts` | 保留 |
+| `ops_task_executions` | 保留 |
+| `ops_remote_executions` | 建议新增，记录远程批量执行任务级审计 |
+| `ops_ansible_playbooks` | 如保留 Ansible 页面则保留，否则删除 |
+| `ops_ansible_jobs` | 同上 |
+| `ops_ansible_inventories` | 同上 |
+
+#### 审批
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `approval_templates` | 替换 `sys_approval_templates` |
+| `approval_processes` | 保留 |
+| `approval_steps` | 保留 |
+| `approval_workflows` | 替换 `sys_approval_workflows` |
+| `approval_workflow_steps` | 替换 `sys_approval_workflow_steps` |
+
+建议：模板保留表单 schema，工作流表保留审批流定义，流程实例引用 `workflow_id`，逐步弱化 `flow_config` JSON。
+
+#### AIOps / AI
+
+| 目标表 | 来源/处理 |
+| --- | --- |
+| `ai_llm_configs` | 保留 |
+| `ai_chat_histories` | 保留 |
+| `ai_analysis_traces` | 保留 |
+| `ai_runs` | 保留 |
+| `ai_run_messages` | 保留 |
+| `ai_run_spans` | 保留 |
+| `ai_capabilities` | 保留 |
+| `ai_capability_policies` | 保留 |
+| `ai_ops_sessions` | 替换 `ops_sessions` |
+| `ai_ops_commands` | 替换 `ops_commands` |
+
+### 重建执行策略
+
+1. 修改所有 `TableName()`，把目标表名一次性统一。
+2. 修改 GORM many2many tag：`role_permissions` -> `iam_role_permissions`。
+3. 修改硬编码 `db.Table(...)` 和 SQL 清理逻辑。
+4. 精简 AutoMigrate：删除已合并/废弃模型，补上漏迁移模型。
+5. 更新 seed：默认权限、审批模板、工具配置、演示数据按新表生成。
+6. 删除测试库数据卷或 SQLite 文件，重新启动服务让 AutoMigrate 建表。
+7. 跑 `go build`、`npx tsc --noEmit`、集成测试和关键页面验证。
+
+## 总体结论
+
+当前表名前缀没有形成统一分层，主要使用 `asset_`、`monitor_`、`ops_`、`deploy_`、`sys_`、`iam_`、`ai_`、`kubernetes_`。整体可以运行，但存在几类需要后续整改的问题：
+
+1. **无前缀或前缀不一致表**：`approval_processes`、`approval_steps`、`navigation_links`、`metric_values`、`dashboard_panels`、`snmp_history`、`role_permissions`。
+2. **同一职责多套表并存**：审批有 `sys_approval_templates / approval_processes / approval_steps` 与 `sys_approval_workflows / sys_approval_workflow_steps`；监控大屏有 `monitor_dashboards / dashboard_panels` 与 `monitor_custom_dashboards`；告警规则有 `AlertRule` 和 `MonitorAlertRule` 共用 `monitor_alert_rules`。
+3. **表定义但迁移/引用不完整**：`SNMPHistory` 定义了 `snmp_history`，但未进入 AutoMigrate，代码实际查询 `ops_snmp_metrics`；`AgentPortPolicy` 有控制器引用，但未进入 AutoMigrate。
+4. **疑似旧表/低价值表**：`sys_log_sources`、`sys_log_entries` 属于旧日志模块，与当前日志中心 `monitor_log_datasources` + 外部 Loki/ES 架构重复；`ops_ansible_*` 有种子数据但“远程执行”现已主要走 SSH/脚本执行，需要确认是否仍保留 Ansible 页面。
+5. **设计一致性问题**：大量 JSON 字符串字段承载结构化配置，短期可接受，但要明确边界；高频时序表缺少统一保留策略和分区方案；部分关联表缺少显式外键/唯一约束命名规范。
+
+## 现状前缀评估
+
+> 本节是现状评估口径；重建整改时以“重建版目标设计”为准。
+
+| 领域 | 当前/建议前缀 | 说明 |
+| --- | --- | --- |
+| IAM/权限/凭据 | `iam_` | 用户、角色、权限、LDAP、凭据、ItemRole |
+| 系统基础配置 | `sys_` | 系统任务、站内导航、全局配置 |
+| 安全审计 | `audit_` | 重建后从 `sys_` 拆出，避免系统配置与审计数据混在一起 |
+| 资产/云资源 | `asset_` | 服务器、云账号、域名、账单、资源模型 |
+| Kubernetes | `k8s_` | 重建后统一短前缀，替换当前 `kubernetes_` |
+| 发布/部署 | `deploy_` | 环境、凭据、工具、发布记录、成员权限 |
+| 自动化执行 | `ops_` | 定时任务、脚本、任务执行、远程执行记录 |
+| 监控告警 | `monitor_` | 指标、目标、告警、数据源、站点拨测、SNMP、Agent |
+| 审批 | `approval_` | 重建后模板、流程、实例统一归入审批域 |
+| AI/AIOps | `ai_` | LLM 配置、会话、分析轨迹、能力策略 |
+
+## 问题清单
+
+| 编号 | 严重度 | 表/模型 | 问题 | 建议 |
+| --- | --- | --- | --- | --- |
+| DB-001 | 高 | `AlertRule` / `MonitorAlertRule` -> `monitor_alert_rules` | 两个模型返回同一张表，字段定义不同。AutoMigrate 会叠加字段，后续维护容易误删/误覆盖。 | 合并为一个模型或拆成 `monitor_alert_rules` 与 `monitor_probe_alert_rules`，迁移前确认线上字段使用。 |
+| DB-002 | 高 | `AgentPortPolicy` -> `monitor_agent_port_policy` | 控制器有读写，但未加入 AutoMigrate，新库端口策略接口可能报“表不存在”。 | 加入 AutoMigrate；表名建议改为复数 `monitor_agent_port_policies`，如改名需迁移旧表。 |
+| DB-003 | 高 | `SNMPHistory` -> `snmp_history` | 定义未迁移，代码未引用；清理逻辑清的是 `ops_snmp_metrics`。 | 若 `ops_snmp_metrics` 已兼任历史表，删除 `SNMPHistory`；否则新增迁移并把查询/清理改到 `monitor_snmp_histories`。 |
+| DB-004 | 中 | `approval_processes`、`approval_steps` | 审批流程表无前缀，而模板表是 `sys_approval_templates`。 | 重建后统一为 `approval_templates`、`approval_processes`、`approval_steps`、`approval_workflows`。 |
+| DB-005 | 中 | `sys_approval_workflows`、`sys_approval_workflow_steps` | 与 `sys_approval_templates.flow_config` 和 `approval_steps` 职责有重叠。 | 明确“模板流程配置”和“流程定义管理”的关系；如果新工作流已替代模板内 JSON，应迁移数据并下线旧字段。 |
+| DB-006 | 中 | `navigation_links` | 导航组是 `sys_navigation_groups`，链接表无前缀。 | 重建后改为 `sys_navigation_links`。 |
+| DB-007 | 中 | `metric_values`、`monitor_metric_histories`、`monitor_metrics_aggregate` | 监控时序有三套表：原始值、简化历史、聚合；当前控制器大量使用 `monitor_metric_histories`，`metric_values` 引用少。 | 重建后合并为 `monitor_metric_samples` + `monitor_metric_aggregates`。 |
+| DB-008 | 已处理 | `monitor_dashboards`、`monitor_dashboard_panels` | 自定义大屏旧模型与路由已删除，统一使用 `monitor_dashboards` + `monitor_dashboard_panels`。 | 后续仅补齐新大屏 API/页面。 |
+| DB-009 | 中 | `role_permissions` | GORM many2many 明确指定为 `role_permissions`，无 `iam_` 前缀。 | 重建后改为 `iam_role_permissions`。 |
+| DB-010 | 中 | `sys_log_sources`、`sys_log_entries` | 旧日志采集/入库表，与当前日志中心外部数据源架构重复。 | 重建后删除，日志中心只保留 `monitor_log_datasources` 和外部查询结果。 |
+| DB-011 | 中 | `ops_site_*`、`ops_snmp_*` | 站点拨测和 SNMP 属于监控域，但表名前缀使用 `ops_`。 | 重建后改为 `monitor_site_*`、`monitor_snmp_*`。 |
+| DB-012 | 中 | `ai_runs`、`ops_sessions`、`ops_commands` | AI 运行表和人机执行会话跨 `ai_` / `ops_`，边界不清。 | 重建后改为 `ai_ops_sessions`、`ai_ops_commands`。 |
+| DB-013 | 低 | `backend/model/monitor.go`、`deploy_tool.go` | 模型文件超过或接近项目红线，维护成本高。 | 后续按子域拆分：target/metric/dashboard/health_probe/tool_registry。 |
+
+## 菜单域表清单
+
+### 仪表盘
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 首页统计 | 多域聚合，无独立主表 | 统计来自资产、告警、K8s、流水线等表，合理。 |
+| 自定义监控仪表盘 | `monitor_dashboards`、`monitor_dashboard_panels` | 已统一到监控大屏主表和面板表。 |
+
+### 资产管理 / 云资源
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 服务器管理 | `asset_servers` | 前缀规范；字段较多但与 Agent/RDP/SSH 场景匹配。 |
+| 主机组 | `asset_host_groups` | 放资产域合理。 |
+| 云平台 | `asset_clouds` | 命名偏泛，实际是云平台类型/供应商。可考虑改为 `asset_cloud_platforms`。 |
+| 云账号 | `asset_cloud_accounts` | 前缀规范；凭证字段需确认是否已统一走 `iam_credentials` 加密。 |
+| 云区域 | `asset_regions` | 前缀规范；如果仅云区域，建议 `asset_cloud_regions` 更清晰。 |
+| 域名管理 | `asset_domains` | 前缀规范。 |
+| 资源型号 | `asset_resource_models` | 前缀规范。 |
+| 云账单 | `asset_cloud_billings` | 前缀规范。 |
+| 账单告警规则 | `monitor_billing_alert_rules` | 归入监控域合理，但与资产账单强关联，需文档化。 |
+
+### Kubernetes
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 集群管理 | `kubernetes_clusters` | 当前统一 `kubernetes_` 前缀，虽较长但一致。 |
+| 节点缓存 | `kubernetes_nodes` | 从集群同步缓存，合理。 |
+| Pod 缓存 | `kubernetes_pods` | 从集群同步缓存，合理。 |
+| Deployment 缓存 | `kubernetes_deployments` | 从集群同步缓存，合理。 |
+| Service 缓存 | `kubernetes_services` | 从集群同步缓存，合理。 |
+| Ingress 缓存 | `kubernetes_ingresses` | 从集群同步缓存，合理。 |
+| 拓扑布局 | `kubernetes_topology_layouts` | 用户布局数据，合理。 |
+
+建议：重建后统一改为 `k8s_`，后续不再新增 `kubernetes_` 表。
+
+### 应用发布 / CI/CD
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 流水线 | `ops_pipelines` | 历史命名属 `ops_`，但该域现在已经有 `deploy_` 前缀，建议长期统一。 |
+| 流水线运行 | `ops_pipeline_runs` | 同上；日志存在 `logs longtext`，数据增长需清理策略。 |
+| 应用发布 | `deploy_app_releases` | 前缀规范。 |
+| Git 仓库配置 | `deploy_pipeline_repos` | 可能与统一凭据 `iam_credentials` 存在职责重叠，当前通过 `credential_id` 关联可接受。 |
+| 镜像仓库配置 | `deploy_pipeline_registries` | 同上。 |
+| 发布环境 | `deploy_environments` | 前缀规范。 |
+| 构建节点 | `deploy_build_nodes`、`deploy_build_master_config` | 前缀规范。 |
+| 流水线成员 | `deploy_pipeline_members` | 前缀规范；直接用户 + 用户组双授权设计合理。 |
+| 发布用户组 | `deploy_user_groups`、`deploy_user_group_members` | 前缀规范，但与 IAM 角色/组职责需边界清晰。 |
+| ItemRole | `iam_item_roles`、`iam_user_item_roles` | 放 IAM 域合理，用于流水线正则授权。 |
+| 工具配置 | `deploy_tools` | 前缀规范。 |
+
+建议：重建后统一改为 `deploy_pipelines`、`deploy_pipeline_runs`。
+
+### 监控告警
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 告警规则/事件 | `monitor_alert_rules`、`monitor_alert_events` | 主表合理；但规则模型重复是高风险问题。 |
+| 告警条件/模板/升级/静默 | `monitor_alert_conditions`、`monitor_alert_notify_templates`、`monitor_alert_upgrades`、`monitor_alert_upgrade_records`、`monitor_alert_silences` | 前缀规范；需确认哪些已接入 UI/引擎。 |
+| 通知渠道/联系人 | `monitor_notify_channels`、`monitor_alert_contacts`、`monitor_alert_contact_groups`、`monitor_alert_notify_policies`、`monitor_alert_notify_settings` | 前缀规范；通知设置/策略/模板职责较多，建议后续画数据流。 |
+| Agent 指标 | `monitor_agent_reports`、`monitor_metrics_aggregate` | 前缀规范；按 hostname 关联服务器，删除服务器时有清理。 |
+| Agent 任务/规则/告警 | `monitor_agent_tasks`、`monitor_agent_rules`、`monitor_agent_alerts` | 前缀规范。 |
+| Agent 端口策略 | `monitor_agent_port_policy` | 未迁移，且表名非复数。 |
+| 监控目标/指标 | `monitor_targets`、`monitor_metrics`、`monitor_metric_histories`、`monitor_metric_tags`、`metric_values` | 需要统一时序表职责和命名前缀。 |
+| 健康探针 | `monitor_health_probes` | 前缀规范；结果不独立入库，随 Agent 心跳更新。 |
+| Prometheus/Zabbix/日志/链路数据源 | `monitor_prometheus_datasources`、`monitor_zabbix_datasources`、`monitor_log_datasources`、`monitor_trace_datasources` | 前缀规范。 |
+| 站点拨测 | `ops_site_tasks`、`ops_site_results`、`ops_site_alerts` | 功能属监控，前缀却是 `ops_`。 |
+| SNMP | `ops_snmp_devices`、`ops_snmp_templates`、`ops_snmp_template_oids`、`ops_snmp_metrics`、`ops_snmp_interfaces`、`snmp_history` | 功能属监控；`snmp_history` 未迁移/未引用。 |
+| 指标目录旧表 | `monitor_metric_data` | 需确认是否仍有 UI/引擎依赖；可能与 `monitor_metrics` 重复。 |
+
+### 自动化运维
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 定时任务 | `ops_cron_jobs` | 前缀规范。 |
+| 脚本库 | `ops_scripts` | 前缀规范。 |
+| 执行记录 | `ops_task_executions` | 前缀规范。 |
+| Ansible | `ops_ansible_playbooks`、`ops_ansible_jobs`、`ops_ansible_inventories` | 有模型和种子数据；需确认 UI 是否仍作为主功能。若已由 Go-native SSH 替代，可降级为 deprecated。 |
+
+### AIOps / AI
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| LLM 配置 | `ai_llm_configs` | 前缀规范。 |
+| 对话历史 | `ai_chat_histories` | 前缀规范。 |
+| 告警分析轨迹 | `ai_analysis_traces` | 前缀规范。 |
+| Agent CLI 运行 | `ai_runs`、`ai_run_messages`、`ai_run_spans` | 前缀规范。 |
+| 能力注册/策略 | `ai_capabilities`、`ai_capability_policies` | 前缀规范。 |
+| 人机执行会话 | `ops_sessions`、`ops_commands` | 与 AI Agent 强关联但用 `ops_`，边界需确认。 |
+
+### 资源申请 / 审批
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 审批模板 | `sys_approval_templates` | 前缀规范。 |
+| 审批实例 | `approval_processes` | 无前缀。 |
+| 审批步骤 | `approval_steps` | 无前缀。 |
+| 审批工作流 | `sys_approval_workflows`、`sys_approval_workflow_steps` | 前缀规范，但与模板内 `flow_config` 和实例步骤存在职责重叠。 |
+
+建议：先确认现行前端使用旧模板流程还是新 workflow；再决定迁移方向。
+
+### 安全审计
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 操作审计 | `sys_audit_logs` | 前缀规范。 |
+| 审计策略 | `sys_audit_settings` | 前缀规范。 |
+| 登录日志 | `sys_login_logs` | 前缀规范。 |
+| 终端会话 | `sys_terminal_sessions` | 前缀规范。 |
+| RDP 会话 | `sys_rdp_sessions` | 前缀规范。 |
+| 会话命令 | `sys_session_commands` | 前缀规范。 |
+
+### 系统管理 / IAM
+
+| 功能 | 表 | 评价 |
+| --- | --- | --- |
+| 用户 | `iam_users` | 前缀规范。 |
+| 角色 | `iam_roles` | 前缀规范。 |
+| 权限 | `iam_permissions` | 前缀规范。 |
+| 用户角色关系 | `iam_user_roles` | GORM many2many 指定，前缀规范。 |
+| 角色权限关系 | `role_permissions` | GORM many2many 指定，无 `iam_` 前缀。 |
+| LDAP | `iam_ldap_configs` | 前缀规范。 |
+| 凭据 | `iam_credentials` | 前缀规范；建议继续作为全局凭据统一入口。 |
+| 日志范围权限 | `monitor_log_scope_roles`、`monitor_user_log_scope_roles` | 属日志中心/监控域，放 `monitor_` 合理。 |
+| 系统任务状态 | `sys_system_task_status` | 前缀规范。 |
+| 站内导航 | `sys_navigation_groups`、`navigation_links` | 链接表无前缀。 |
+
+## 疑似可清理候选
+
+测试库重建时可直接删除；生产整改前仍需查数据量、最近写入时间、controller/frontend 是否仍有入口。
+
+| 表/模型 | 判断依据 | 建议动作 |
+| --- | --- | --- |
+| `snmp_history` / `SNMPHistory` | 未 AutoMigrate，未被业务引用。 | 重建后删除模型。 |
+| `sys_log_sources`、`sys_log_entries` | 旧日志入库模块，与日志中心外部数据源重复。 | 重建后删除。 |
+| `monitor_custom_dashboards` | 与 `monitor_dashboards` 重复。 | 已删除模型与路由，重建后不再创建。 |
+| `metric_values`、`monitor_metric_histories` | 时序职责重复。 | 重建后合并为 `monitor_metric_samples`。 |
+| `ops_ansible_*` | 远程执行主路径已偏 Go-native SSH。 | 若确认无页面入口，重建后删除；否则保留在 `ops_`。 |
+| `deploy_pipeline_repos`、`deploy_pipeline_registries` | Pipeline 已直接使用 `GitCredentialID` / `RegistryCredentialID`。 | 已删除模型、路由和前端旧配置入口，重建后不再创建。 |
+
+## 迁移清单之外的 8 个模型决策（2026-08-04）
+
+以下清单由 `TableName()` 与原 AutoMigrate 列表逐项比对得出。生产库不得再通过启动期 AutoMigrate 隐式创建这些表；后续仅允许由版本化迁移创建已确认保留的表。
+
+| 模型 / 表 | 决策 | 依据与后续动作 |
+| --- | --- | --- |
+| `LogSource` / `sys_log_sources` | 保留 | 已有日志源 CRUD 路由。纳入首批基线迁移并保留数据。 |
+| `LogEntry` / `sys_log_entries` | 保留 | 已有查询与 Agent 日志写入逻辑。纳入首批基线迁移，并在保留策略中按高频日志数据处理。 |
+| `MetricData` / `monitor_metric_data` | DTO 化 | 仅被仪表盘作为 API 响应结构使用，不读写该表。后续移除 `TableName()`，不再创建或写入该表。 |
+| `MetricTag` / `monitor_metric_tags` | 暂不建表 | 当前没有 controller、service 或前端调用。保留类型定义待“指标样本模型”统一设计完成，再以独立迁移启用。 |
+| `MetricValue` / `monitor_metric_values` | 暂不建表 | 当前没有读写路径，且与 `monitor_metric_histories` 职责重叠。统一时序模型前不得创建新表。 |
+| `MonitorDashboard` / `monitor_dashboards` | 废弃 | 无业务引用；当前大屏走既有配置与外部数据源路径。后续删除模型定义，不纳入迁移。 |
+| `DashboardPanel` / `monitor_dashboard_panels` | 废弃 | 仅被废弃 `MonitorDashboard` 关联引用。后续随父模型删除，不纳入迁移。 |
+| `SNMPHistory` / `snmp_history` | 废弃 | 无业务引用，SNMP 当前实际数据表为 `ops_snmp_metrics`。后续删除模型，不纳入迁移。 |
+
+> 上述“暂不建表”和“废弃”均不执行生产 DROP TABLE；删除旧表须先完成数据量、最近写入时间、备份与恢复演练检查。
+
+## 后续整改顺序
+
+1. **先统一命名和模型归属**：按 Schema v2 修改 `TableName()`、many2many tag、硬编码 SQL。
+2. **处理重复模型**：合并 `AlertRule` / `MonitorAlertRule`、大屏表、指标时序表、审批 workflow/模板关系。
+3. **删除废弃模型**：`SNMPHistory`、旧日志入库、旧仓库/镜像仓库配置、确认不用的 Ansible 表。
+4. **重建测试库**：删除 SQLite 文件或 Docker 数据卷，让 AutoMigrate 从零建表。
+5. **补充数据生命周期**：流水线日志、Agent 报告、指标样本、SNMP 样本、站点拨测结果、审计日志都需要保留期和清理任务。

docs/deployment.md

@@ -160,9 +160,14 @@ mysql:8.0  +  redis:7-alpine  +  aiops (Dockerfile)
 环境变量（可选）：
 
 ```bash
-VERSION=v1.5.0 MYSQL_PASSWORD=xxx ./run.sh docker up
+cp .env.example .env
+chmod 600 .env
+# 填写 MYSQL_ROOT_PASSWORD、MYSQL_PASSWORD、JWT_SECRET 后再启动
+VERSION=v1.5.0 ./run.sh docker up
 ```
 
+Compose 不再为密码或 JWT 提供不安全默认值；缺少任一必要值会拒绝启动。MySQL/Redis 端口仅绑定本机回环地址，Docker Socket 不会挂载给 AIOps 容器。
+
 ### 推送镜像
 
 ```bash
@@ -172,12 +177,14 @@ VERSION=v1.5.0 MYSQL_PASSWORD=xxx ./run.sh docker up
 
 ### 连接外部数据库
 
-使用 `docker-compose.k8s.yml`（仅单应用容器，挂载 `backend/config.external.yaml`）：
+使用 `docker-compose.k8s.yml`（仅单应用容器，连接外部 MySQL/Redis）：
 
 ```bash
 VERSION=v1.5.0 docker compose -f docker-compose.k8s.yml up -d --build
 ```
 
+该方式要求在 `.env`（权限 `600`）提供 `DATABASE_HOST`、`DATABASE_USER`、`DATABASE_PASSWORD`、`REDIS_HOST` 和 `JWT_SECRET`；uploads 使用命名卷持久化。
+
 ### 管理命令
 
 ```bash
@@ -268,10 +275,12 @@ K8s 探针使用 `/version`。
 ## 生产配置建议
 
 1. **数据库**：生产使用 MySQL + Redis（`MODE=release`），local 模式仅适合单副本
-2. **JWT Secret**：更换默认密钥
-3. **版本**：生产环境 pin 镜像 tag（`lghost/aiops:v1.5.0`），避免使用 `:dev`
-4. **HTTPS**：Ingress 或前置 Nginx 终止 TLS
-5. **备份**：定期备份 MySQL 数据和 PVC
+2. **Secret**：通过 Secret 管理系统或权限为 `600` 的 `.env` 注入数据库密码和至少 32 字节 JWT；不得提交真实值
+3. **运行身份**：镜像默认以非 root UID `10001` 运行；不得恢复 Docker Socket 或 `hostNetwork` 挂载
+4. **持久化**：备份 MySQL 数据、SQLite/redka PVC 和 uploads PVC，并定期验证恢复
+5. **网络**：K8s 的 `deployment.yaml` 内置 MySQL/Redis NetworkPolicy；在收集 Ingress/Agent 出口 CIDR 后继续收紧 AIOps 入站规则
+6. **版本**：生产环境 pin 镜像 tag（`lghost/aiops:v1.5.0`），避免使用 `:dev`
+7. **HTTPS**：Ingress 或前置 Nginx 终止 TLS
 
 ---
 
@@ -283,4 +292,4 @@ K8s 探针使用 `/version`。
 | `Dockerfile` | embed 单容器镜像（推荐） |
 | `docker-compose.yml` | MySQL + Redis + AIOps |
 | `deploy/kubernetes/deployment.yaml` | K8s Deployment + NodePort |
-| `.gitignore` | 忽略 `aiops`、`backend/aiops*` 等编译产物 |
+| `.gitignore` | 忽略 `aiops`、`backend/aiops*` 等编译产物 |

docs/development-guide.md

@@ -51,7 +51,7 @@ feat: 添加服务器批量导入功能
 | `middleware/` | JWT / 日志 / CORS 中间件 |
 | `router/` | 路由注册 |
 | `service/` / `repository/` | 业务逻辑 / 数据访问 |
-| `pkg/database/` | 数据库连接 + AutoMigrate |
+| `pkg/database/` | 数据库连接 + 显式基线建表能力 |
 | `pkg/agentcli/` | Agent CLI 引擎（ReAct + Evolver） |
 | `pkg/remoteexec/` | Go-native SSH 远程执行 |
 | `static/` | 前端 embed 静态资源 |
@@ -235,6 +235,7 @@ go build -o aiops .
 cd frontend
 npm run build
 npx tsc --noEmit   # 类型检查（提交前零错误）
+npm run lint        # ESLint（提交前零错误）
 ```
 
 ### 独立二进制构建
@@ -247,9 +248,15 @@ npx tsc --noEmit   # 类型检查（提交前零错误）
 ### 集成测试
 
 ```bash
-python3 tests/integration_test.py --host localhost --port 8080
+# 测试账号必须显式传入，避免对生产或共享环境误用默认凭证
+AIOPS_TEST_USERNAME=admin AIOPS_TEST_PASSWORD='测试密码' \
+  python3 tests/integration_test.py --host localhost --port 8080
 ```
 
+### GitHub Actions CI
+
+`.github/workflows/ci.yml` 在 `master` / `dev` 的推送与 Pull Request 上并行执行后端、Agent、前端和 SQLite + redka API 集成测试。前端 ESLint 采用阻断模式；仓库已有的 lint 错误会使 CI 失败，必须修复后才会恢复通过，不能以忽略错误的方式放行。
+
 ## 日志
 
 | 级别 | 使用场景 |

docs/quick-start.md

@@ -112,7 +112,7 @@ docker login
 
 ### 开发模式
 
-默认 SQLite，数据库由后端自动迁移（AutoMigrate）。
+默认 SQLite。首次初始化请显式执行 `./aiops migrate up`；服务启动不会自动修改数据库结构。详见 [数据库版本化迁移](database-migrations.md)。 // Logan.Li
 
 ### local 二进制模式
 

docs/reference/database-schema.md

@@ -7,7 +7,7 @@ AIOps 使用 GORM 作为 ORM 框架，支持 SQLite / MySQL / PostgreSQL。
 - **默认**: SQLite（零配置，数据文件 `backend/data/aiops.db`）
 - **生产**: 推荐使用 MySQL 或 PostgreSQL
 
-首次启动时，`AutoMigrate` 会自动创建所有表。
+首次初始化请显式执行 `aiops migrate up` 创建基线；服务启动时不会自动修改表结构。迁移流程见 [数据库版本化迁移](../database-migrations.md)。 // Logan.Li
 
 ## 数据模型
 
@@ -168,18 +168,9 @@ approval_templates ──< approval_processes ──< approval_steps
 navigation_groups ──< navigation_links
 ```
 
-## AutoMigrate
+## 版本化迁移
 
-表结构在 `backend/pkg/database/database.go` 中定义，服务启动时自动执行：
-
-```go
-func AutoMigrate(db *gorm.DB) error {
-    return db.AutoMigrate(
-        &models.User{}, &models.Role{}, &models.Permission{},
-        &models.Server{}, &models.Cloud{}, ...
-    )
-}
-```
+模型基线由 `backend/pkg/database/database.go` 的 `BootstrapSchema` 定义，但只允许由 `aiops migrate up` 显式调用。后续变更按版本存放在 `backend/migrations/`，并记录至 `sys_schema_migrations`；已运行的服务不会在启动期间执行迁移。 // Logan.Li
 
 ## 切换数据库
 

docs/specs/README.md

@@ -0,0 +1,105 @@
+# AIOps 规格驱动开发规范
+
+本目录保存会改变系统行为、接口、数据或运维方式的工程规格。规格的作用是让需求、实现、测试和发布使用同一套可验证契约。
+
+## 1. 适用范围
+
+按最高影响级别判定，不以改动行数判断：
+
+| 级别 | 范围 | 必需产物 |
+|------|------|----------|
+| S0 | 文案、格式、注释、无行为变化的机械修改 | 验证记录 |
+| S1 | 局部缺陷、内部重构、单模块小改动 | 任务计划中的问题、约束和验收标准 |
+| S2 | 新功能、跨模块流程、API、配置、数据模型变更 | `docs/specs/<domain>/<slug>.md` |
+| S3 | 权限、安全、账单、迁移、数据清理、生产部署 | S2 规格 + 风险、兼容、可观测、发布、回滚 |
+
+连续开发同一能力时更新已有规格，不重复创建。纯探索或评估可以先输出调研结论；一旦进入实现，必须补齐对应级别的规格。
+
+## 2. 事实与优先级
+
+规格必须基于仓库和运行环境的真实证据。发生冲突时按以下顺序处理：
+
+1. 用户当前明确需求与已确认决策。
+2. 已接受规格中的验收标准和契约。
+3. 安全、数据保护和生产变更规则。
+4. 自动化测试表达的现有行为。
+5. 当前实现与一般文档。
+
+当前实现与规格不一致时不得自行选择其一：先确认这是缺陷、兼容要求还是规格过期，然后更新规格中的决策记录。
+
+## 3. 生命周期
+
+规格状态使用：`Draft`、`Accepted`、`Implemented`、`Verified`、`Superseded`。
+
+1. **Discover**：定位入口、调用链、数据模型、权限、外部依赖、现有测试和工作区改动。
+2. **Specify**：定义目标和非目标，用 `FR-*`、`NFR-*`、`AC-*` 编号描述行为与验收。
+3. **Design**：明确模块边界、契约、失败路径、迁移、观测和回滚，记录关键取舍。
+4. **Implement**：小步实现并保持范围受控；新增发现通过规格的决策记录显式吸收。
+5. **Verify**：建立 `AC → 测试/检查 → 结果` 的可追踪关系，覆盖成功、失败和边界路径。
+6. **Deliver**：更新状态、列出变更、验证证据、部署结果、遗留风险与后续工作。
+
+用户需求已经足够明确时，维护者可将规格标记为 `Accepted` 并继续实现。只有未决选择会改变用户可见行为、数据安全、权限或部署风险时才需要等待确认。
+
+## 4. 规格质量要求
+
+### 4.1 需求必须可验证
+
+- 使用“当……时，系统必须……”描述行为，避免“优化一下”“尽量”“支持更多”等不可验证表述。
+- 每项功能需求使用 `FR-01` 编号，每项非功能需求使用 `NFR-01` 编号。
+- 每条验收标准使用 `AC-01` 编号，并给出输入、动作和可观察结果。
+- 非目标必须明确，防止实现阶段自然扩张范围。
+
+### 4.2 契约必须先于实现
+
+- HTTP/API：路径、方法、请求、响应、错误码、鉴权、幂等和分页口径。
+- 数据：表/字段、约束、索引、默认值、迁移顺序、回填、兼容窗口和回滚限制。
+- UI：入口、权限、加载/空/错误/禁用状态、响应式行为和中英文文案。
+- 任务/事件：触发方式、重试、超时、去重、并发、状态机和审计记录。
+- 外部系统：限流、超时、部分失败、降级、凭证边界和供应商差异。
+
+### 4.3 AIOps 领域约束
+
+- 金额：原币、报告币、汇率来源、生效时间、舍入精度和汇总维度必须明确。
+- 时间：时区、采样区间、自然日/月边界、数据截止时间和缺失数据处理必须明确。
+- 监控：指标单位、标签基数、采样频率、保留期、告警迟滞和恢复条件必须明确。
+- 自动化：执行身份、目标范围、危险操作确认、超时、取消、重试和审计必须明确。
+- AI：输入数据范围、提示上下文、置信度含义、不可用降级和结果免责声明必须明确。
+
+## 5. 验证门禁
+
+验证范围随风险扩大，但至少包括受影响模块：
+
+| 变更 | 最低验证 |
+|------|----------|
+| Go 后端 | 相关 `go test`、`go vet`、`go build` |
+| React 前端 | `tsc --noEmit`、目标 ESLint、生产构建、关键页面验证 |
+| Agent | `go test ./...`、`CGO_ENABLED=0 go build`、协议兼容检查 |
+| API/跨模块 | Handler/服务测试 + 前后端契约检查 + 关键流程验证 |
+| 数据库 | 各支持方言迁移测试、幂等性、备份与回滚演练说明 |
+| 生产部署 | `/version`、迁移状态、进程/日志、关键只读接口、回滚点 |
+
+不能运行的检查必须记录具体原因和残余风险。既有失败要区分是否由本次变更引入，不能静默忽略。
+
+## 6. 完成定义
+
+只有同时满足以下条件，规格才可标记为 `Verified`：
+
+- 所有 `FR-*` 已实现，所有 `AC-*` 都有通过证据。
+- API、数据、权限、审计、错误状态和兼容行为与规格一致。
+- 相关自动化测试、静态检查和构建通过。
+- S3 已验证备份、发布、健康检查和回滚路径。
+- 用户文档、运维文档、配置示例和规格状态已同步。
+- 未完成项和已知风险已显式记录，不用模糊措辞掩盖。
+
+## 7. 文件组织
+
+```text
+docs/specs/
+├── README.md
+├── _template.md
+├── cloud/billing-normalization.md
+├── monitor/site-probe-retention.md
+└── deploy/pipeline-jenkins.md
+```
+
+文件名使用小写短横线。规格中引用代码、API、迁移和测试的实际路径。重大方向被替代时保留原规格并标记 `Superseded`，不要删除决策历史。

docs/specs/_template.md

@@ -0,0 +1,88 @@
+# <规格名称>
+
+| 字段 | 内容 |
+|------|------|
+| 状态 | Draft |
+| 级别 | S2 / S3 |
+| 负责人 | Logan.Li |
+| 创建日期 | YYYY-MM-DD |
+| 最后更新 | YYYY-MM-DD |
+| 关联任务 | <链接或说明> |
+
+## 1. 背景与证据
+
+描述当前行为、问题和触发本变更的证据，引用实际代码、接口、日志或数据。
+
+## 2. 目标与非目标
+
+### 目标
+
+- <本次必须达成的结果>
+
+### 非目标
+
+- <明确不在本次处理的事项>
+
+## 3. 用户场景
+
+- 当 <角色> 在 <条件> 下执行 <动作> 时，系统必须 <可观察结果>。
+
+## 4. 需求
+
+### 功能需求
+
+- `FR-01`：<确定、可验证的行为要求>。
+
+### 非功能需求
+
+- `NFR-01`：<性能、安全、可靠性、兼容性或可维护性要求>。
+
+## 5. 设计与契约
+
+### 模块边界
+
+说明复用点、所有权和不应新增的重复能力。
+
+### API / 事件
+
+列出路径、方法、请求、响应、错误码、权限、幂等、超时与重试。
+
+### 数据与迁移
+
+列出字段、约束、索引、默认值、回填、兼容窗口、数据量影响和迁移版本。
+
+### UI / 交互
+
+列出入口、权限、加载、空、错误、禁用、响应式和国际化状态。
+
+## 6. 风险与可观测性
+
+| 风险/失败模式 | 防护或降级 | 观测信号 |
+|---------------|------------|----------|
+| <风险> | <处理方式> | <日志/指标/任务状态> |
+
+## 7. 验收标准
+
+- `AC-01`：给定 <前置条件>，当 <动作>，则 <可观察结果>。
+- `AC-02`：给定 <异常或边界条件>，当 <动作>，则 <失败行为或降级结果>。
+
+## 8. 验证追踪
+
+| 验收标准 | 测试或检查 | 结果 |
+|----------|------------|------|
+| AC-01 | `<命令、测试名或人工步骤>` | Pending |
+| AC-02 | `<命令、测试名或人工步骤>` | Pending |
+
+## 9. 发布与回滚
+
+说明发布顺序、配置/迁移前置条件、健康检查、备份、回滚步骤和不可逆事项。S3 必填。
+
+## 10. 决策记录
+
+| 日期 | 决策 | 原因与影响 |
+|------|------|------------|
+| YYYY-MM-DD | <决定> | <依据、取舍和影响范围> |
+
+## 11. 遗留事项
+
+- <不阻塞本次验收但需要后续跟踪的工作>

docs/specs/repository/source-reconciliation.md

@@ -0,0 +1,92 @@
+# 本地、生产服务器与远程仓库源码统一
+
+| 字段 | 内容 |
+|------|------|
+| 状态 | Accepted |
+| 级别 | 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` | Pending |
+| AC-02 | 双向 `rsync --dry-run --checksum --delete`（排除运行文件） | Pending |
+| AC-03 | `go test/go vet/go build`、`tsc`、ESLint、Vite build、Agent build | Pass（2026-08-05） |
+| AC-04 | Linux 构建、`/version`、`migrate status`、进程和日志检查 | Pending |
+| AC-05 | 提交文件审计与生产文件哈希/存在性检查 | Pending |
+
+## 8. 发布与回滚
+
+发布前保存本地和服务器源码归档、Git bundle、生产二进制及数据库现有备份。若统一源码验证失败，不更新远程分支或现有工作区。若生产切换失败，恢复上一二进制并保留统一提交供离线修复。远程分支更新使用预期旧哈希或 `--force-with-lease` 防止覆盖并发提交。
+
+## 9. 决策记录
+
+| 日期 | 决策 | 原因与影响 |
+|------|------|------------|
+| 2026-08-05 | 服务器源码为结构基线，本地独有有效能力采用合并而非删除 | 服务器包含较新的组件拆分，本地包含当前生产二进制所需的新能力 |
+| 2026-08-05 | 生产配置与运行数据不纳入源码一致性 | 防止泄密和破坏运行环境 |
+
+## 10. 遗留事项
+
+- 统一完成后应使用同一主分支开发，禁止继续在生产工作区直接形成长期未提交改动。

docs/sqlite-maintenance-runbook.md

@@ -0,0 +1,30 @@
+# SQLite 维护与恢复演练 Runbook
+
+适用范围：独立二进制或 local 模式的 SQLite 数据库。生产维护只能在批准的维护窗口执行；高峰期及存在活跃写入时禁止 `VACUUM`。
+
+## 维护前检查
+
+1. 确认近期备份可读取，并记录当前数据库、WAL 文件大小。
+2. 在发布窗口停止 AIOps 写入进程；`VACUUM` 期间必须保持停写。
+3. 使用绝对路径，禁止将 `/`、工作区或未核实的路径作为维护目标。
+
+```bash
+./scripts/sqlite-maintenance.sh \
+  --maintenance-window \
+  --db /srv/aiops/sqlite3.db \
+  --backup-dir /srv/aiops/backups/sqlite \
+  --pid-file /srv/aiops/.aiops.pid
+```
+
+脚本会先执行 SQLite `.backup`，对备份运行 `PRAGMA integrity_check`，再执行 `wal_checkpoint(TRUNCATE)`、`VACUUM` 和最终完整性检查。备份校验失败时不会进入空间回收步骤。
+
+## 恢复演练
+
+1. 在隔离测试目录复制一份备份，绝不直接覆盖生产库。
+2. 用同版本二进制指向副本启动，并验证 `/version`、管理员登录、服务器列表和近期 Agent 指标查询。
+3. 对副本执行 `PRAGMA integrity_check`，并记录恢复耗时、RPO、RTO 与验证结果。
+4. 仅当演练通过后，更新备份巡检记录；生产恢复须由值班负责人批准并保留原库只读副本。
+
+## 线上当前风险
+
+`sqlite3.db` 与 WAL 已达到多 GB 级别。请先完成备份恢复演练，再安排维护窗口；本次整改不会在在线服务上直接运行 `VACUUM`。