docs: 同步 README 与 docs 至最新部署与版本方案

- 更新三种部署方式：embed 单容器、./aiops 根目录二进制
- 补充版本管理、release、lghost/aiops 镜像推送说明
- 修正过时的 docker 4 容器、backend/aiops、run.sh start 等描述
- 更新 project-structure、deployment、quick-start 等核心文档

README.md

@@ -13,10 +13,11 @@
 
 ### 后端
 - Go 1.24 / Gin Web Framework
-- GORM (ORM) / MySQL 8.0 / Redis 7
+- GORM (ORM) / MySQL 8.0 / Redis 7 / SQLite (local 模式)
 - JWT 认证 / Zap 日志 / Viper 配置
 - WebSocket (Gorilla) / PTY 终端 (creack/pty)
 - 自研轻量 Kubernetes HTTP 客户端（channel.k8s.io WebSocket 协议）
+- go:embed 嵌入前端静态资源（单二进制 / 单容器部署）
 
 ### Agent
 - Go 1.24 静态编译 (CGO_ENABLED=0)
@@ -27,135 +28,113 @@
 
 | 方式 | 命令 | 架构 | 适用场景 |
 |------|------|------|----------|
-| **① 独立二进制** | `./run.sh build` → `./run.sh binary` | 单文件，前后端一体 | 无 Docker/K8s 环境 |
+| **① 独立二进制** | `./run.sh build` → `./aiops` | 单文件 embed，输出到项目根目录 | 无 Docker/K8s，边缘/本机 |
-| **② Kubernetes** | `./run.sh kubernetes deploy` | Embed 单容器 + MySQL/Redis StatefulSet | 生产集群，devops 命名空间 |
+| **② Docker Compose** | `./run.sh docker up` | 3 容器 (MySQL + Redis + AIOps embed) | 单机生产、演示 |
-| **③ Docker Compose** | `./run.sh docker up` | 4 容器 (MySQL+Redis+Backend+Nginx) | 单机生产，开发/测试 |
+| **③ Kubernetes** | `./run.sh kubernetes deploy` | embed 单容器 + MySQL/Redis StatefulSet | 生产集群，`devops` 命名空间 |
 
 统一入口 `./run.sh`，详见 `./run.sh help`。
 
+### 版本与镜像
+
+- **发布版本**：Git tag 为权威来源（如 `v1.5.0`）
+- **Docker 镜像**：`lghost/aiops:<tag>`（Docker Hub）
+- **二进制版本**：`./aiops version` / `GET /version`
+- **一键发版**：`./run.sh release v1.5.0`（打 tag → 编译二进制 → 构建镜像 → 推送 Docker Hub → 更新 K8s manifest）
+
+```bash
+docker login
+./run.sh release v1.5.0
+./aiops version                              # 查看二进制版本
+curl http://localhost:8080/version           # 查看运行版本
+```
+
 ## 快速开始
 
-### Docker Compose 部署
-
-```bash
-# 一键启动全部服务 (MySQL + Redis + 后端 + Nginx 前端)
-./run.sh docker up
-
-# 访问
-# 前端: http://localhost:80
-# 后端: http://localhost:8080
-# 健康检查: http://localhost:8080/health
-
-# 管理
-./run.sh docker logs      # 查看日志
-./run.sh docker ps        # 容器状态
-./run.sh docker down      # 停止
-```
-
-### Kubernetes 部署
-
-```bash
-# 一键部署到 devops 命名空间
-./run.sh kubernetes deploy
-
-# 访问: http://<NODE_IP>:30080
-
-# 运维
-./run.sh kubernetes status       # 资源状态
-./run.sh kubernetes logs         # 应用日志
-./run.sh kubernetes upgrade      # 重新构建 + 滚动更新
-./run.sh kubernetes exec         # 进入容器 Shell
-./run.sh kubernetes mysql        # 进入 MySQL CLI
-./run.sh kubernetes redis        # 进入 Redis CLI
-./run.sh kubernetes scale 3      # 扩缩容
-./run.sh kubernetes port-forward # 端口转发到本机
-./run.sh kubernetes delete       # 删除所有 K8s 资源（保留 PVC）
-./run.sh kubernetes build        # 仅构建 embed 镜像
-```
-
-### 独立二进制部署
-
-```bash
-# 编译（前端自动嵌入）
-./run.sh build
-
-# 启动
-./backend/aiops                                      # 默认 SQLite, 端口 8080
-./backend/aiops --port 9090                         # 自定义端口
-./backend/aiops --db-driver mysql --db-host ...     # MySQL 模式
-```
-
 ### 本地开发
 
 ```bash
 ./run.sh dev               # 前端 :5173 + 后端 :8080 (热重载)
-
+./run.sh stop              # 停止
-# 单独启动
+./run.sh status            # 查看状态
-cd frontend && npm run dev
-cd backend && go run .
 ```
 
+### Docker Compose 部署
+
+```bash
+./run.sh docker up              # 构建并启动 (MySQL + Redis + AIOps)
+./run.sh docker up v1.5.0       # 指定版本构建
+./run.sh docker push v1.5.0     # 构建并推送到 lghost/aiops
+
+# 访问（前后端同一端口）
+# http://localhost:8080
+# http://localhost:8080/version
+```
+
+### Kubernetes 部署
+
+```bash
+./run.sh kubernetes deploy           # 构建镜像 + 全量部署
+./run.sh kubernetes upgrade v1.5.0   # 指定版本滚动更新
+./run.sh kubernetes push v1.5.0      # 构建并推送 Docker Hub
+
+# 访问: http://<NODE_IP>:30080
+# 镜像: lghost/aiops:<tag>
+```
+
+### 独立二进制部署
+
+```bash
+./run.sh build                    # 编译到项目根目录 ./aiops
+./run.sh build tag v1.5.0         # 指定版本编译
+./aiops version                   # 查看版本
+./aiops --mode local              # 本地模式 (SQLite + redka)
+./run.sh binary upgrade           # 停服 → 重编译 → 后台启动
+```
+
+> Mac 上 `./run.sh build` 产出 **darwin** 二进制，仅本机可用。  
+> Linux 服务器请在 Linux 上构建，或使用 Docker/K8s embed 镜像（`Dockerfile.embed` 固定 `GOOS=linux GOARCH=amd64`）。
+
 ### Agent 构建
 
 ```bash
-./run.sh build agent       # 交叉编译 Agent (amd64+arm64)
+./run.sh build agent       # 交叉编译 Agent (linux-amd64 + linux-arm64)
 
-# 验证
+./agent/aiops-agent-linux-amd64 version
-./agent/bin/aiops-agent-linux-amd64 version
-./agent/bin/aiops-agent-linux-amd64 output -top-n 3    # Zabbix 风格指标输出
 ```
 
 ### 默认账号
 
-- 用户名: `admin`
+| 用户名 | 密码 | 角色 |
-- 密码: `123456`
+|--------|------|------|
+| admin | 123456 | 超级管理员 |
+| ops01 | 123456 | 运维 |
+| dev01 | 123456 | 开发 |
 
 ## 项目结构
 
 ```
 aiops/
 ├── frontend/                    # 前端 (React + TypeScript)
-│   ├── src/components/          # dashboard/server/kubernetes/monitor/deploy/aiops...
+│   ├── src/components/          # dashboard/server/k8s/monitor/deploy/aiops...
-│   ├── src/services/            # API + HTTP 封装
+│   └── Dockerfile               # [legacy] 独立 Nginx 镜像，Compose 已改用 embed
-│   ├── src/store/               # Zustand 状态管理
-│   └── Dockerfile               # nginx:alpine 镜像
 │
 ├── backend/                     # 后端 (Go + Gin)
-│   ├── main.go                 # 入口 (was cmd/main.go)
+│   ├── main.go                  # 应用入口
-│   ├── embed.go                # 前端嵌入 (was cmd/embed.go)
+│   ├── embed.go                 # go:embed 前端静态资源
-│   ├── config/                 # 配置加载 (was internal/config)
+│   ├── static/                  # 前端构建产物（embed 目标目录）
-│   ├── controller/             # HTTP 处理器 (was internal/api/handlers)
+│   ├── controller/              # HTTP 处理器
-│   ├── middleware/             # JWT/日志/CORS (was internal/api/middleware)
+│   ├── router/                  # 路由注册
-│   ├── router/                 # 路由注册 (was internal/api/routes)
+│   ├── model/                   # GORM 数据模型
-│   ├── model/                  # GORM 数据模型 (was internal/models)
+│   ├── pkg/                     # database/kubernetesclient/remoteexec/...
-│   ├── cloud/                  # 云平台对接 (was internal/cloud)
+│   └── Dockerfile               # [legacy] 分离式后端镜像
-│   ├── dto/                    # 请求/响应传输对象 ★
-│   ├── repository/             # 数据访问层 ★
-│   ├── service/                # 业务逻辑层 ★
-│   ├── utils/                  # 工具函数 ★
-│   ├── seed/                   # 种子数据 (was cmd/seed.go)
-│   ├── static/                 # 前端构建产物 (was cmd/static/)
-│   ├── pkg/                    # 公共包 (database/kubernetesclient/remoteexec/toolinstaller)
-│   └── Dockerfile              # 3 阶段构建 (Go build → Agent → Alpine Runtime)
 │
-├── agent/                       # 监控 Agent
+├── agent/                       # 监控 Agent（独立 Go module）
-│   ├── collector/               # /proc 指标采集
+├── deploy/kubernetes/           # K8s 部署清单 (devops 命名空间)
-│   ├── task/                    # 远程任务执行
+├── docker-compose.yml           # MySQL + Redis + AIOps embed（3 容器）
-│   └── reporter/                # HTTP 上报
+├── docker-compose.k8s.yml       # 单应用容器（连接外部 DB）
-│
+├── Dockerfile.embed             # embed 单容器镜像（推荐）
-├── deploy/kubernetes/           # Kubernetes 部署清单
-│   ├── namespace.yaml           # devops 命名空间
-│   ├── secret.yaml              # 密钥
-│   ├── configmap.yaml           # 配置
-│   ├── mysql.yaml               # MySQL StatefulSet
-│   ├── redis.yaml               # Redis StatefulSet
-│   ├── deployment.yaml          # AIOps Deployment + NodePort Service
-│   └── ingress.yaml             # Ingress 路由
-│
-├── docker-compose.yml           # Docker Compose 4 容器编排
-├── Dockerfile.embed             # Embed 单容器镜像 (前端→后端→Agent→Runtime)
 ├── run.sh                       # 统一入口脚本
-└── Makefile                     # 快捷命令
+└── aiops                        # 独立二进制产物（gitignore，项目根目录）
 ```
 
 ## 核心功能
@@ -164,21 +143,25 @@ aiops/
 |------|------|
 | 仪表盘 | 成本统计、告警聚合、Top 资源、SSL 提醒、趋势图表 |
 | 资产管理 | 服务器 CRUD、批量导入、WebShell、云账号/域名/账单 |
-| Kubernetes 管理 | 多集群管理、Deployment 三模式编辑器(查看/可视化编辑/YAML)、Node/Pod/Service/Ingress、kubectl 终端、事件聚合、多集群对比、Namespace 管理 |
+| Kubernetes 管理 | 多集群、Deployment 三模式编辑器、Pod 终端/文件浏览、事件聚合 |
-| 应用发布 | CI/CD 流水线（GitLab CI 风格可视化）、发布配置、SSH 主机 + Kubernetes 双路径部署 |
+| 应用发布 | CI/CD 流水线、发布配置、SSH + K8s 双路径部署 |
-| 监控中心 | 监控大屏、主机指标（CPU/内存/磁盘/网络/进程/端口/FD）、告警规则引擎、飞书/钉钉通知 |
+| 监控中心 | 监控大屏、主机指标、告警引擎、飞书/钉钉通知 |
-| 自动化运维 | 定时任务、脚本库（Shell/Python）、远程执行（Go-native SSH）、Ansible |
+| 自动化运维 | 定时任务、脚本库、远程执行（Go-native SSH） |
-| AIOps 智能 | AI 智能助手（6 种 LLM）、告警分析、容量预测 |
+| AIOps 智能 | AI 助手、告警分析、容量预测 |
 | 资源申请 | 云服务器/应用部署申请审批 |
-| 系统管理 | 用户管理、角色权限、操作审计、终端审计、凭证配置、系统设置 |
+| 系统管理 | 用户/角色、操作审计、凭证配置 |
 
-### Kubernetes 管理亮点
+## 文档
 
-- **Deployment 三模式编辑器**: 查看模式 / 可视化编辑（5 Tab: 基本信息·容器信息·存储挂载·高级设置·服务路由）/ YAML 编辑（CodeMirror 6 语法高亮）
+详细开发文档见 [docs/README.md](./docs/README.md)。
-- **StatefulSet/DaemonSet**: 完整详情页（更新策略/选择器/PVC 模板/Init Containers）
+
-- **Pod 交互**: 文件浏览器（上传/下载）、exec 终端（WebSocket channel.k8s.io）、日志流
+| 文档 | 说明 |
-- **集群运维**: 事件聚合看板、多集群对比（雷达图/柱状图）、Node 详情（资源分配率/污点/容器运行时）、Namespace CRUD（资源配额）
+|------|------|
-- **自研轻量客户端**: 不依赖 client-go，net/http + WebSocket 直连 K8s API
+| [快速开始](./docs/quick-start.md) | 环境准备、本地开发 |
+| [部署指南](./docs/deployment.md) | 二进制 / Docker / K8s / 版本发版 |
+| [开发规范](./docs/development-guide.md) | 代码规范、Git 工作流 |
+| [项目结构](./docs/project-structure.md) | 目录结构说明 |
+| [CLAUDE.md](./CLAUDE.md) | AI 助手指引（完整命令参考） |
 
 ## License
 

docs/BACKEND_SUMMARY.md

@@ -1,16 +1,21 @@
 # AIOps 后端项目总结
 
+> **注意**：目录结构已重构，入口为 `backend/main.go`，处理器在 `controller/`。  
+> 最新结构见 [project-structure.md](./project-structure.md)，部署见 [deployment.md](./deployment.md)。
+
 ## 项目概述
 
 AIOps 后端是一个基于 Go + Gin 框架开发的专业 AIOps 智能运维平台 API 服务。  
+前端通过 `go:embed` 嵌入 `backend/static/`，支持单二进制与 embed 单容器部署。
 
-## 项目结构
+## 项目结构（历史参考，部分路径已变更）
 
 ```
 backend/
-├── cmd/
+├── main.go                        # 应用入口（当前）
-│   └── main.go                    # 应用入口
+├── embed.go                       # 前端静态资源嵌入
-├── internal/
+├── controller/                    # HTTP 处理器（原 handlers）
+├── internal/                      # [已迁移] 见下方历史结构
 │   ├── api/
 │   │   ├── handlers/              # HTTP 处理器
 │   │   │   ├── user.go           # 用户管理
@@ -265,11 +270,11 @@ docker-compose up -d mysql redis
 ### 4. 运行
 
 ```bash
-# 开发模式
+# 推荐：项目根目录
-go run cmd/main.go
+./run.sh dev
 
-# 或使用 Makefile
+# 或仅后端
-make run
+cd backend && go run .
 ```
 
 ### 5. 生成 Mock 数据

docs/PROJECT_SUMMARY.md

@@ -186,11 +186,11 @@ cp config.yaml.example config.yaml
 # 启动数据库
 docker-compose up -d mysql redis
 
-# 运行
+# 运行（推荐统一入口）
-go run cmd/main.go
+./run.sh dev
 
-# 或使用 Makefile
+# 或仅后端
-make run
+cd backend && go run .
 ```
 
 ## API 文档
@@ -199,27 +199,26 @@ make run
 
 ## 部署
 
-### Docker 部署
+> 最新部署方式见 [deployment.md](./deployment.md)。
 
 ```bash
-# 前端
+# 独立二进制
-cd app
+./run.sh build tag v1.5.0 && ./aiops --mode local
-docker build -t ezops-frontend .
-docker run -p 80:80 ezops-frontend
 
-# 后端
+# Docker Compose（embed 单容器 + MySQL + Redis）
-cd backend
+./run.sh docker up
-docker build -t ezops-backend .
-docker run -p 8080:8080 -v $(pwd)/config.yaml:/app/config.yaml ezops-backend
 
-# 或使用 Docker Compose
+# Kubernetes
-docker-compose up -d
+./run.sh kubernetes deploy
+
+# 发版推送 Docker Hub
+./run.sh release v1.5.0    # → lghost/aiops:v1.5.0
 ```
 
 ## 默认账号
 
 - **用户名**: admin
-- **密码**: admin123
+- **密码**: 123456
 
 ## 注意事项
 

docs/README.md

@@ -1,17 +1,17 @@
 # AIOps 开发文档
 
-本目录包含 AIOps 智能运维平台的全部开发文档。
+本目录包含 AIOps 智能运维平台的开发文档。
 
 ## 文档索引
 
 | 文档 | 说明 |
 |------|------|
+| [快速开始](./quick-start.md) | 环境准备、本地开发、常见问题 |
+| [部署指南](./deployment.md) | 二进制 / Docker / K8s 部署、版本发版、镜像推送 |
 | [项目结构](./project-structure.md) | 前后端目录结构说明 |
-| [快速开始](./quick-start.md) | 环境准备、安装、启动 |
+| [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
 | [API 接口](./api-reference.md) | 后端 API 接口文档 |
 | [数据库设计](./database-schema.md) | 数据模型和表结构 |
-| [开发规范](./development-guide.md) | 代码规范、Git 工作流 |
-| [部署指南](./deployment.md) | 生产环境部署 |
 | [开发日志](./dev-log.md) | 详细开发日志（按日期记录） |
 | [Redis 缓存策略](./redis-caching-strategy.md) | Redis 缓存使用现状与优化方案 |
 
@@ -25,12 +25,30 @@
 
 ## 根目录文档
 
-以下文档位于项目根目录：
-
 | 文档 | 说明 |
 |------|------|
-| [ROADMAP.md](../ROADMAP.md) | K8s 管理功能演进路线图 |
-| [TDD_PLAN.md](../TDD_PLAN.md) | TDD 验证计划 |
-| [PROJECT_EVALUATION.md](../PROJECT_EVALUATION.md) | K8s 管理功能评估基线 |
 | [README.md](../README.md) | 项目主说明 |
-| [CLAUDE.md](../CLAUDE.md) | AI 助手指引 |
+| [CLAUDE.md](../CLAUDE.md) | AI 助手指引（完整命令与规范） |
+| [ROADMAP.md](../ROADMAP.md) | K8s 管理功能演进路线图 |
+
+## 部署速查
+
+| 场景 | 命令 |
+|------|------|
+| 本地开发 | `./run.sh dev` |
+| 编译二进制 | `./run.sh build tag v1.5.0` → `./aiops` |
+| Docker Compose | `./run.sh docker up` → http://localhost:8080 |
+| K8s 部署 | `./run.sh kubernetes deploy` |
+| 发版推送 | `./run.sh release v1.5.0` → `lghost/aiops:v1.5.0` |
+| 查看版本 | `./aiops version` / `curl /version` |
+
+## 部署架构（当前）
+
+```
+开发:     ./run.sh dev          → 5173 + 8080 热重载
+二进制:   ./run.sh build        → ./aiops (embed, 项目根目录)
+Compose:  ./run.sh docker up    → mysql + redis + aiops (embed, :8080)
+K8s:      ./run.sh kubernetes   → lghost/aiops:<tag> embed 单 Pod
+```
+
+> 前后端分离的 Nginx 容器已废弃，统一使用 `Dockerfile.embed` 单容器方案。

docs/deployment.md

@@ -1,139 +1,286 @@
 # 部署指南
 
-## 开发环境
+本文档描述 AIOps 的三种部署方式、版本管理和镜像发布流程。
 
-参见 [快速开始](./quick-start.md)。
+## 部署方式概览
 
-```bash
+| 方式 | 命令 | 容器/产物 | 前端 | 数据库 |
-./run.sh start
+|------|------|-----------|------|--------|
+| 独立二进制 | `./run.sh build` | `./aiops`（项目根目录） | go:embed | 默认 SQLite + redka |
+| Docker Compose | `./run.sh docker up` | 3 容器 | embed 单端口 8080 | MySQL + Redis |
+| Kubernetes | `./run.sh kubernetes deploy` | embed 单 Pod | embed 单端口 8080 | 集群内 MySQL/Redis 或 local 模式 |
+
+> **已废弃**：前后端分离的 4 容器 Compose（Backend + Nginx）已合并为 embed 单应用容器。
+
+---
+
+## 版本管理
+
+### 原则
+
+```
+Git tag (v1.5.0)  →  唯一发布版本
+       ↓
+  ┌────┴────┬──────────────┐
+  │         │              │
+./aiops   lghost/aiops   K8s deployment
+ version   :v1.5.0       image: lghost/aiops:v1.5.0
 ```
 
-## 生产构建
+### 版本解析优先级
 
-### 后端编译
+`run.sh` 中 `resolve_version()` 统一处理：
+
+1. 显式参数（`./run.sh build tag v1.5.0`）
+2. 环境变量 `VERSION=v1.5.0`
+3. `git describe --tags --always --dirty`
+4. 兜底 `dev`
+
+### 查看版本
 
 ```bash
-cd backend
+./aiops version
-CGO_ENABLED=1 go build -ldflags="-s -w" -o aiops-server cmd/main.go
+./aiops --version
+curl http://localhost:8080/version
 ```
 
-### 前端构建
+响应示例：
 
-```bash
+```json
-cd app
+{
-npm run build  # 输出到 dist/
+  "version": "v1.5.0",
-```
+  "build_time": "2026-06-26T08:26:52Z",
-
+  "git_commit": "9f5ce24",
-### 使用 Makefile
+  "mode": "local",
-
+  "db_driver": "sqlite",
-```bash
+  "redis_driver": "redka"
-make build  # 同时构建前后端
-```
-
-## Docker 部署
-
-### Dockerfile
-
-后端已有 `backend/Dockerfile`，可基于此构建镜像。
-
-```bash
-cd backend
-docker build -t aiops-server .
-```
-
-### docker-compose
-
-```bash
-cd backend
-docker-compose up -d
-```
-
-## Nginx 反向代理
-
-前端构建后部署到 Nginx，后端 API 反向代理：
-
-```nginx
-server {
-    listen 80;
-    server_name aiops.example.com;
-
-    # 前端静态文件
-    location / {
-        root /usr/share/nginx/html;
-        try_files $uri $uri/ /index.html;
-    }
-
-    # 后端 API 代理
-    location /api/ {
-        proxy_pass http://127.0.0.1:8080;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-    }
-
-    # WebSocket 代理
-    location /ws/ {
-        proxy_pass http://127.0.0.1:8080;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-    }
 }
 ```
 
-参考配置文件：`backend/nginx.conf`
+### 一键发版
 
-## 系统服务（systemd）
+```bash
+docker login
+./run.sh release v1.5.0
+```
 
-创建 `/etc/systemd/system/aiops.service`：
+依次执行：
+
+1. 创建 git tag `v1.5.0`（已存在则跳过）
+2. 编译独立二进制 `./aiops`（ldflags 注入版本）
+3. 构建 Docker 镜像 `lghost/aiops:v1.5.0`
+4. 推送到 Docker Hub
+5. 更新 `deploy/kubernetes/deployment.yaml` 镜像坐标
+
+发版后可选：
+
+```bash
+git push origin master
+git push origin v1.5.0
+```
+
+---
+
+## ① 独立二进制
+
+### 编译
+
+```bash
+./run.sh build                  # 自动解析版本
+./run.sh build tag v1.5.0       # 指定版本
+```
+
+产物固定输出到 **项目根目录** `./aiops`，不会在 `backend/` 下生成。
+
+构建前会自动清理历史产物：`backend/aiops*`。
+
+### 启动
+
+```bash
+./aiops --mode local            # SQLite + redka（默认推荐）
+./aiops --port 9090
+./aiops --config config.yaml
+
+# 后台守护进程
+./run.sh binary upgrade
+./run.sh binary status
+./run.sh binary stop
+```
+
+### 平台说明
+
+| 构建环境 | `./aiops` 格式 | 用途 |
+|----------|---------------|------|
+| macOS Apple Silicon | darwin/arm64 | 仅 Mac 本机 |
+| macOS Intel | darwin/amd64 | 仅 Mac 本机 |
+| Linux x86_64 | linux/amd64 | Linux 服务器 |
+
+Mac 上 `./run.sh build` **不能**产出 Linux 二进制；Linux 部署请用 Docker 镜像或在 Linux 上构建。
+
+### systemd 示例
 
 ```ini
 [Unit]
-Description=AIOps Server
+Description=AIOps
 After=network.target
 
 [Service]
 Type=simple
-User=www-data
+User=aiops
 WorkingDirectory=/opt/aiops
-ExecStart=/opt/aiops/aiops-server
+ExecStart=/opt/aiops/aiops --mode local --port 8080
 Restart=always
 RestartSec=5
-Environment=GIN_MODE=release
 
 [Install]
 WantedBy=multi-user.target
 ```
 
-```bash
+---
-systemctl enable aiops
+
-systemctl start aiops
+## ② Docker Compose
+
+### 架构（3 容器）
+
+```
+mysql:8.0  +  redis:7-alpine  +  aiops (Dockerfile.embed)
+                                      ↓
+                              http://localhost:8080
+                         (API + WebSocket + 前端 SPA)
 ```
 
-## 环境变量
+### 启动
 
-| 变量 | 默认值 | 说明 |
+```bash
-|------|--------|------|
+./run.sh docker up
-| PORT | 8080 | 后端端口 |
+./run.sh docker up v1.5.0       # 指定版本
-| GIN_MODE | debug | Gin 模式（release/debug） |
+./run.sh docker up fresh        # 无缓存全量重建
-| GOPROXY | - | Go 模块代理 |
+```
 
-## 生产配置建议
+环境变量（可选）：
 
-1. **数据库**: 生产环境使用 MySQL/PostgreSQL，不要用 SQLite
+```bash
-2. **JWT Secret**: 更换为高强度随机字符串
+VERSION=v1.5.0 MYSQL_PASSWORD=xxx ./run.sh docker up
-3. **CORS**: 生产环境配置允许的具体域名，不要用 `*`
+```
-4. **HTTPS**: 配置 TLS 证书
+
-5. **日志**: 使用文件日志 + 日志轮转
+### 推送镜像
-6. **备份**: 定期备份数据库
+
+```bash
+./run.sh docker push v1.5.0
+# 等价于 docker push lghost/aiops:v1.5.0
+```
+
+### 连接外部数据库
+
+使用 `docker-compose.k8s.yml`（仅单应用容器，挂载 `backend/config.external.yaml`）：
+
+```bash
+VERSION=v1.5.0 docker compose -f docker-compose.k8s.yml up -d --build
+```
+
+### 管理命令
+
+```bash
+./run.sh docker ps
+./run.sh docker logs
+./run.sh docker down
+./run.sh docker clean           # 清理构建缓存
+```
+
+---
+
+## ③ Kubernetes
+
+### 镜像
+
+- 默认镜像：`lghost/aiops:<tag>`
+- 构建文件：`Dockerfile.embed`
+- 命名空间：`devops`
+- 访问：`http://<NODE_IP>:30080`
+
+### 部署
+
+```bash
+./run.sh kubernetes deploy
+./run.sh kubernetes deploy v1.5.0
+```
+
+### 滚动更新
+
+```bash
+./run.sh kubernetes upgrade v1.5.0
+```
+
+### 推送镜像（Mac 可构建 Linux 镜像）
+
+```bash
+./run.sh kubernetes push v1.5.0
+```
+
+`Dockerfile.embed` 内固定 `GOOS=linux GOARCH=amd64`，在 Mac 上 `docker build` 产出的是 Linux 镜像。
+
+### 运维命令
+
+```bash
+./run.sh kubernetes status
+./run.sh kubernetes logs
+./run.sh kubernetes exec
+./run.sh kubernetes mysql
+./run.sh kubernetes redis
+./run.sh kubernetes scale 3       # 多副本自动切换 release + MySQL 模式
+./run.sh kubernetes port-forward
+./run.sh kubernetes delete
+```
+
+### 内网部署说明
+
+若 K8s 节点无法访问 Docker Hub：
+
+1. **推荐**：同步到内网 Harbor，修改 `deployment.yaml` 中 `image` 为内网地址
+2. **离线**：`docker save` → `scp` → 节点 `docker load`
+
+运行节点（如 10.10.10.73/75）只需 `pull` 镜像，不需要把镜像文件直接推到服务器磁盘。
+
+---
+
+## Mac 构建 Linux 镜像
+
+| 操作 | Mac 支持 | 说明 |
+|------|---------|------|
+| `./run.sh build` | ✅（darwin 二进制） | 仅本机运行 |
+| `docker build` (Dockerfile.embed) | ✅ | 产出 linux/amd64 镜像 |
+| `docker push lghost/aiops:tag` | ✅ | 需 `docker login` |
+| `./run.sh release v1.x` | ✅ | 完整发版流程 |
+
+---
 
 ## 健康检查
 
 ```bash
-# 检查后端是否正常
+curl http://localhost:8080/version    # 推荐（无 DB 强依赖）
-curl http://localhost:8080/health
+curl http://localhost:8080/health   # 含 DB 检查
-# {"status":"ok"}
-
-# 检查版本
-curl http://localhost:8080/version
-# {"version":"dev","build_time":"...","git_commit":"..."}
 ```
+
+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
+
+---
+
+## 相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `run.sh` | 统一入口（build/docker/kubernetes/release） |
+| `Dockerfile.embed` | embed 单容器镜像（推荐） |
+| `docker-compose.yml` | MySQL + Redis + AIOps |
+| `deploy/kubernetes/deployment.yaml` | K8s Deployment + NodePort |
+| `.gitignore` | 忽略 `aiops`、`backend/aiops*` 等编译产物 |

docs/development-guide.md

@@ -44,14 +44,16 @@ feat: 添加服务器批量导入功能
 
 | 目录 | 职责 |
 |------|------|
-| `cmd/` | 应用入口 |
+| `main.go` / `embed.go` | 应用入口 + 前端嵌入 |
-| `internal/handlers/` | HTTP 请求处理（参数校验、响应） |
+| `controller/` | HTTP 请求处理（参数校验、响应） |
-| `internal/models/` | 数据模型定义 |
+| `model/` | 数据模型定义 |
-| `internal/config/` | 配置管理 |
+| `config/` | 配置管理 (Viper) |
-| `internal/middleware/` | 中间件 |
+| `middleware/` | JWT / 日志 / CORS 中间件 |
-| `internal/routes/` | 路由注册 |
+| `router/` | 路由注册 |
-| `pkg/database/` | 数据库连接 |
+| `service/` / `repository/` | 业务逻辑 / 数据访问 |
+| `pkg/database/` | 数据库连接 + AutoMigrate |
 | `pkg/logger/` | 日志工具 |
+| `static/` | 前端 embed 静态资源 |
 
 ### 命名规范
 
@@ -169,8 +171,16 @@ go test -v ./...
 ### 前端构建测试
 
 ```bash
-cd app
+cd frontend
-npm run build  # TypeScript 编译 + Vite 构建
+npm run build
+npx tsc --noEmit   # 类型检查（提交前零错误）
+```
+
+### 独立二进制构建
+
+```bash
+./run.sh build tag v1.5.0
+./aiops version
 ```
 
 ## 日志

docs/project-structure.md

@@ -4,152 +4,82 @@
 
 ```
 aiops/
-├── frontend/                    # 前端 (React 18 + TypeScript + Vite)
+├── frontend/                    # 前端 (React 19 + TypeScript + Vite)
 │   ├── src/
-│   │   ├── components/          # 业务组件（每个 <700行，超限已模块化拆分）
+│   │   ├── components/          # 业务组件（单文件 <700 行）
 │   │   │   ├── agent/           # Agent 监控
-│   │   │   ├── aiops/           # AI 智能运维（AIPredictiveAnalytics 含 PredictiveCapacityTab）
+│   │   │   ├── aiops/           # AI 智能运维
-│   │   │   ├── approval/        # 审批流程（ApprovalFlow + Process/Template Tab）
+│   │   │   ├── approval/        # 审批流程
-│   │   │   ├── audit/           # SQL 审计
+│   │   │   ├── automation/      # 自动化运维
-│   │   │   ├── automation/      # 自动化运维（CronJob/Script/Ansible）
+│   │   │   ├── cloud/           # 云平台管理
-│   │   │   ├── cloud/           # 云平台管理（CloudBilling + Helpers 子组件）
+│   │   │   ├── dashboard/       # 仪表盘
-│   │   │   ├── dashboard/       # 仪表盘（Charts/Recent/Stats 子组件）
 │   │   │   ├── deploy/          # CI/CD 部署
-│   │   │   ├── k8s/             # K8s 集群管理（Detail/Dialog/Topology 子组件）
+│   │   │   ├── k8s/             # K8s 集群管理
-│   │   │   ├── layout/          # 布局组件
+│   │   │   ├── monitor/         # 监控告警
-│   │   │   ├── monitor/         # 监控告警（AlertManager + Events/Rules Tab + Dialog 子组件）
+│   │   │   ├── server/          # 服务器管理
-│   │   │   │   ├── alert-center/ # 告警中心（AlertCenter + Detail 子组件）
+│   │   │   ├── system/          # 系统管理
-│   │   │   │   ├── dashboard/   # Grafana 仪表盘（GrafanaPanelContent 子组件）
+│   │   │   └── ui/              # shadcn/ui 基础组件
-│   │   │   │   ├── logs/        # 日志管理
-│   │   │   │   └── trace/       # 链路追踪
-│   │   │   ├── navigation/      # 导航管理
-│   │   │   ├── server/          # 服务器管理（ServerManager + Form/BatchImport 子组件）
-│   │   │   ├── system/          # 系统管理（SystemManager + User/Settings/Logs/Roles/LDAP Tab 子组件）
-│   │   │   └── ui/              # shadcn/ui 基础组件（sidebar.tsx + sidebar-context.tsx）
 │   │   ├── hooks/               # 自定义 Hooks
-│   │   ├── lib/                 # 工具库
+│   │   ├── services/            # API 封装 (api.ts / http.ts)
-│   │   ├── mocks/               # Mock 数据（按 domain 模块化，barrel 统一导出）
-│   │   │   ├── data.ts          # Barrel re-export（统一入口）
-│   │   │   └── modules/         # 按业务域分组
-│   │   │       ├── servers.ts   # 服务器/机柜
-│   │   │       ├── cloud.ts     # 云平台
-│   │   │       ├── k8s.ts       # K8s
-│   │   │       ├── alerts.ts    # 告警
-│   │   │       ├── dashboard.ts # 仪表盘
-│   │   │       ├── cicd.ts      # CI/CD
-│   │   │       ├── automation.ts # 自动化
-│   │   │       ├── system.ts    # 系统
-│   │   │       ├── approval.ts  # 审批
-│   │   │       ├── monitor.ts   # 监控
-│   │   │       └── misc.ts      # SQL审计/Ansible/导航等
-│   │   ├── services/            # API 封装
 │   │   ├── store/               # Zustand 状态管理
-│   │   ├── types/               # TypeScript 类型定义
+│   │   └── types/               # TypeScript 类型
-│   │   ├── App.css              # 全局样式
-│   │   ├── App.tsx              # 根组件
-│   │   ├── index.css            # 基础样式
-│   │   └── main.tsx             # 应用入口
 │   ├── package.json
-│   ├── vite.config.ts           # Vite 配置（含 API 代理）
+│   ├── vite.config.ts
-│   ├── tailwind.config.js       # Tailwind CSS 配置
+│   └── Dockerfile               # [legacy] 独立 Nginx 镜像
-│   └── tsconfig.json
 │
-├── backend/                     # 后端 (Go + Gin + GORM)
+├── backend/                     # 后端 (Go 1.24 + Gin + GORM)
-│   ├── cmd/
+│   ├── main.go                  # 应用入口（CLI + HTTP 服务）
-│   │   └── main.go              # 应用入口
+│   ├── embed.go                 # go:embed 前端静态资源
-│   ├── internal/
+│   ├── static/                  # 前端构建产物（embed 目录）
-│   │   ├── api/
+│   ├── config/                  # Viper 配置加载
-│   │   │   ├── handlers/        # HTTP 处理器（模块化拆分）
+│   ├── controller/              # HTTP 处理器
-│   │   │   │   ├── agent.go         # Agent 管理
+│   ├── middleware/              # JWT / 日志 / CORS
-│   │   │   │   ├── agent_task.go    # Agent 任务分发
+│   ├── router/                  # 路由注册
-│   │   │   │   ├── alert.go         # 告警管理
+│   ├── model/                   # GORM 数据模型
-│   │   │   │   ├── alert_engine.go  # 告警引擎
+│   ├── dto/                     # 请求/响应 DTO
-│   │   │   │   ├── ansible.go       # Ansible Playbook
+│   ├── service/                 # 业务逻辑层
-│   │   │   │   ├── approval.go      # 审批流程
+│   ├── repository/              # 数据访问层
-│   │   │   │   ├── audit.go         # 审计日志
+│   ├── seed/                    # 种子数据
-│   │   │   │   ├── automation.go    # 自动化运维（入口）
+│   ├── pkg/                     # 公共包
-│   │   │   │   ├── automation_cron.go     # 定时任务
+│   │   ├── database/            # DB 连接 + AutoMigrate
-│   │   │   │   ├── automation_script.go   # 脚本管理
+│   │   ├── kubernetesclient/    # 轻量 K8s 客户端
-│   │   │   │   ├── automation_playbook.go # Playbook
+│   │   ├── remoteexec/          # Go-native SSH
-│   │   │   │   ├── billing.go       # 云账单
+│   │   └── toolinstaller/       # 工具懒加载
-│   │   │   │   ├── cloud_accounts.go # 云账号
+│   ├── config.yaml              # 默认配置
-│   │   │   │   ├── cloud_domain.go   # 域名
+│   └── Dockerfile               # [legacy] 分离式后端镜像
-│   │   │   │   ├── cloud_platform.go # 云平台
-│   │   │   │   ├── cloud_region.go   # 区域
-│   │   │   │   ├── dashboard.go     # 仪表盘
-│   │   │   │   ├── k8s.go           # K8s 管理
-│   │   │   │   ├── ldap.go          # LDAP（入口）
-│   │   │   │   ├── ldap_ou.go       # LDAP OU 管理
-│   │   │   │   ├── ldap_users.go    # LDAP 用户同步
-│   │   │   │   ├── log.go           # 日志管理
-│   │   │   │   ├── navigation.go    # 导航管理
-│   │   │   │   ├── pipeline.go      # CI/CD 流水线
-│   │   │   │   ├── resource_model.go # 资源模型
-│   │   │   │   ├── server.go        # 服务器管理（入口）
-│   │   │   │   ├── user.go          # 用户认证
-│   │   │   │   ├── user_admin.go    # 用户管理（管理员）
-│   │   │   │   └── webshell.go      # Web 终端
-│   │   │   ├── middleware/      # 中间件
-│   │   │   │   └── auth.go      # JWT 认证 + RBAC
-│   │   │   └── routes/
-│   │   │       └── routes.go    # 路由注册
-│   │   ├── config/
-│   │   │   └── config.go        # 配置加载 (Viper)
-│   │   └── models/              # 数据模型
-│   │       ├── alert.go         # 告警模型
-│   │       ├── approval.go      # 审批模型
-│   │       ├── audit.go         # 审计日志模型
-│   │       ├── automation.go    # 自动化运维模型
-│   │       ├── cicd.go          # CI/CD 模型
-│   │       ├── common.go        # 通用模型 (Response/List/Page)
-│   │       ├── k8s.go           # K8s 模型
-│   │       ├── navigation.go    # 导航模型
-│   │       ├── server.go        # 服务器模型
-│   │       └── user.go          # 用户模型
-│   ├── pkg/
-│   │   ├── database/
-│   │   │   └── database.go      # 数据库连接 + AutoMigrate
-│   │   └── logger/
-│   │       └── logger.go        # Zap 日志
-│   ├── scripts/
-│   │   ├── init.sql             # 初始化 SQL
-│   │   └── mock.go              # Mock 数据生成
-│   ├── config.yaml              # 配置文件（SQLite 默认）
-│   ├── go.mod                   # Go 模块定义
-│   ├── Dockerfile               # Docker 构建
 │
-├── agent/                       # 监控 Agent (Go, 独立 module ezops/agent)
+├── agent/                       # 监控 Agent（独立 Go module）
-│   ├── main.go                  # CLI 入口 (-server/-interval/-token/-hostname)
+│   ├── main.go                  # CLI 入口
-│   ├── collector/               # CPU/mem/disk/port/system 采集器 (/proc)
+│   ├── collector/               # /proc 指标采集
-│   ├── model/model.go           # 上报数据结构 (Report/CPUStat/MemStat/...)
+│   ├── task/                    # 远程任务执行
-│   ├── model/model_ext.go       # 扩展类型 (NetworkStat/DiskIOStat/SystemStat)
+│   ├── reporter/                # HTTP 上报
-│   ├── reporter/http.go         # HTTP POST 上报
+│   └── deploy/                  # install.sh + systemd
-│   ├── task/                    # 远程任务执行 (云助手模式)
-│   ├── deploy/                  # systemd service + install.sh 一键安装
-│   ├── Makefile                 # 交叉编译 amd64+arm64+darwin-arm64
-│   └── bin/                     # 编译产物 (gitignore)
 │
-├── docs/                        # 开发文档
+├── deploy/kubernetes/           # K8s 清单 (devops 命名空间)
-│   ├── README.md                # 文档索引
+│   ├── namespace.yaml
-│   ├── dev-log.md               # 开发日志
+│   ├── deployment.yaml          # embed 单容器, lghost/aiops:<tag>
-│   ├── project-structure.md     # 本文件
+│   ├── mysql.yaml / redis.yaml
-│   ├── quick-start.md           # 快速开始
+│   └── ...
-│   ├── api-reference.md         # API 接口
-│   ├── database-schema.md       # 数据库设计
-│   ├── development-guide.md     # 开发规范
-│   ├── deployment.md            # 部署指南
-│   ├── ROADMAP.md               # 项目路线图
-│   ├── PDD_PLAN.md              # 产品开发计划
-│   ├── PROJECT_SUMMARY.md       # 项目概述
-│   └── BACKEND_SUMMARY.md       # 后端摘要
 │
-├── run.sh                       # 一键启动脚本
+├── docs/                        # 开发文档（本目录）
-├── Makefile                     # 快捷命令
+├── docker-compose.yml           # MySQL + Redis + AIOps embed
-├── .env.example                 # 环境变量模板
+├── docker-compose.k8s.yml       # 单应用 + 外部 DB
-├── .gitignore
+├── Dockerfile.embed             # embed 单容器镜像（推荐）
+├── run.sh                       # 统一入口脚本
+├── aiops                        # 独立二进制产物（gitignore）
 └── README.md
 ```
 
+## 部署相关文件
+
+| 文件 | 用途 |
+|------|------|
+| `run.sh` | build / docker / kubernetes / release 统一入口 |
+| `Dockerfile.embed` | 生产推荐：前端嵌入后端单容器 |
+| `docker-compose.yml` | 3 容器：MySQL + Redis + AIOps |
+| `backend/static/` | `go:embed` 目标，由 `./run.sh build` 同步 |
+| `./aiops` | 独立二进制输出路径（项目根目录） |
+
 ## 技术栈
 
 ### 前端
@@ -168,18 +98,27 @@ aiops/
 
 | 技术 | 版本 | 用途 |
 |------|------|------|
-| Go | 1.21+ | 编程语言 |
+| Go | 1.24+ | 编程语言 |
 | Gin | v1.10+ | Web 框架 |
-| GORM | v1.25+ | ORM 框架 |
+| GORM | v1.25+ | ORM |
-| JWT | v5 (golang-jwt) | 认证 |
+| JWT | v5 | 认证 |
 | Viper | - | 配置管理 |
 | Zap | - | 结构化日志 |
-| SQLite/MySQL/PostgreSQL | - | 数据库 |
+| SQLite / MySQL / Redis | - | 存储 |
 
 ## 端口分配
 
 | 服务 | 端口 | 说明 |
 |------|------|------|
-| 前端 (Vite dev) | 5173 | http://localhost:5173 |
+| 前端 (Vite dev) | 5173 | 开发模式 |
-| 后端 (Gin) | 8080 | http://localhost:8080 |
+| 后端 / embed 部署 | 8080 | API + WebSocket + SPA |
-| 健康检查 | 8080 | http://localhost:8080/health |
+| Docker Compose MySQL | 3306 | 可选暴露 |
+| K8s NodePort | 30080 | 集群外访问 |
+
+## 版本信息注入
+
+编译时通过 ldflags 注入 `main.Version` / `BuildTime` / `GitCommit`：
+
+- `./run.sh build` / `./run.sh build tag v1.5.0`
+- `Dockerfile.embed` 构建参数 `VERSION` / `BUILD_TIME` / `GIT_COMMIT`
+- 运行时：`./aiops version`、`GET /version`

docs/quick-start.md

@@ -4,17 +4,18 @@
 
 | 工具 | 最低版本 | 说明 |
 |------|---------|------|
-| Go | 1.21+ | 后端编译运行（需 CGO 支持 SQLite） |
+| Go | 1.24+ | 后端编译（SQLite 需 CGO_ENABLED=1） |
 | Node.js | 18+ | 前端构建 |
 | npm | 9+ | 包管理 |
-| gcc/clang | - | CGO 编译 SQLite 需要 |
+| gcc/clang | - | CGO 编译 SQLite |
+| Docker | 20+ | 可选，Compose/K8s 部署 |
 
 ### 检查环境
 
 ```bash
-go version        # >= 1.21
+go version
-node -v           # >= 18
+node -v
-gcc --version     # macOS 自带 clang
+./run.sh help
 ```
 
 ## 安装
@@ -30,134 +31,138 @@ cd aiops
 
 ```bash
 make install
-# 或手动安装
+# 或
 cd backend && go mod download && cd ..
-cd frontend cd app &&cd app && npm install && cd ..
+cd frontend && npm install && cd ..
 ```
 
-### 3. 配置（可选）
+## 本地开发（推荐）
-
-默认使用 SQLite，无需任何额外配置即可启动。
-
-如需使用 MySQL 等其他数据库，编辑 `backend/config.yaml`：
-
-```yaml
-database:
-  driver: mysql          # 改为 mysql / postgres
-  host: localhost
-  port: 3306
-  user: root
-  password: your_password
-  dbname: aiops
-```
-
-## 启动
-
-### 方式一：一键启动（推荐）
 
 ```bash
 chmod +x run.sh
-./run.sh start
+./run.sh dev
 ```
 
 输出示例：
+
 ```
-[INFO] ========== AIOps 启动脚本 ==========
+[OK] 后端已启动 (PID: ..., 端口: 8080)
-[INFO] 正在启动后端服务...
+[OK] 前端已启动 (PID: ..., 端口: 5173)
-[INFO] 编译 Go 程序...
-[SUCCESS] 后端服务已启动 (PID: 12345, 端口: 8080)
-[INFO] 正在启动前端服务...
-[SUCCESS] 前端服务已启动 (PID: 12346, 端口: 5173)
-[SUCCESS] ========== 所有服务已启动 ==========
-[INFO] 前端地址: http://localhost:5173
-[INFO] 后端地址: http://localhost:8080
-[INFO] 健康检查: http://localhost:8080/health
 ```
 
-### 方式二：分别启动
-
-```bash
-# 仅后端
-./run.sh backend
-
-# 仅前端
-./run.sh frontend
-```
-
-### 方式三：使用 Makefile
-
-```bash
-make dev      # 启动
-make status   # 查看状态
-make stop     # 停止
-```
-
-## 访问
-
 | 地址 | 说明 |
 |------|------|
-| http://localhost:5173 | 前端界面 |
+| http://localhost:5173 | 前端界面（Vite 热重载） |
-| http://localhost:8080/health | 后端健康检查 |
+| http://localhost:8080 | 后端 API |
 | http://localhost:8080/version | 版本信息 |
-| http://localhost:8080/api/v1/auth/login | 登录接口 |
+| http://localhost:8080/health | 健康检查 |
+
+### 默认账号
+
+- 用户名：`admin`
+- 密码：`123456`
 
 ## 常用命令
 
 ```bash
-./run.sh status    # 查看服务状态
+./run.sh dev        # 启动开发环境
-./run.sh stop      # 停止所有服务
+./run.sh stop       # 停止
-./run.sh restart   # 重启所有服务
+./run.sh restart    # 重启
-./run.sh help      # 查看帮助
+./run.sh status     # 查看状态
-
+./run.sh logs       # 实时日志
-make logs          # 查看实时日志
+./run.sh help       # 完整帮助
-make build         # 构建生产包
-make clean         # 清理构建产物
 ```
 
+## 独立二进制（本机试用）
+
+```bash
+./run.sh build tag v1.0.0    # 编译到 ./aiops
+./aiops version
+./aiops --mode local         # SQLite + redka，零外部依赖
+```
+
+数据文件与二进制同级：`./sqlite3.db`、`./redka.db`。
+
+## Docker Compose（单机演示）
+
+```bash
+./run.sh docker up
+# 访问 http://localhost:8080
+```
+
+## 发版（构建 + 推送镜像）
+
+```bash
+docker login
+./run.sh release v1.5.0
+```
+
+镜像：`lghost/aiops:v1.5.0`
+
 ## 日志位置
 
-| 服务 | 日志文件 |
+| 场景 | 日志 |
-|------|---------|
+|------|------|
-| 后端 | `backend/logs/server.log` |
+| 本地开发后端 | `backend/logs/server.log` |
-| 前端 | `frontend/logs/dev.log` |
+| 本地开发前端 | `frontend/logs/dev.log` |
-| 数据库 | `backend/data/aiops.db`（SQLite 文件） |
+| 独立二进制 | `logs/aiops.log` |
+| Docker | `./run.sh docker logs` |
 
 ## 数据库
 
-默认使用 SQLite，数据库文件位于 `backend/data/aiops.db`，首次启动时自动创建表结构（AutoMigrate）。
+### 开发模式
 
-### 重置数据库
+默认 SQLite，数据库由后端自动迁移（AutoMigrate）。
+
+### local 二进制模式
 
 ```bash
-./run.sh stop
+./aiops --mode local
-rm -f backend/data/aiops.db
+# sqlite3.db / redka.db 在项目根目录
-./run.sh start
+```
+
+### 重置 local 数据
+
+```bash
+./run.sh binary stop
+rm -f sqlite3.db redka.db
+./run.sh binary upgrade
 ```
 
 ## 常见问题
 
-### Q: CGO 编译失败？
+### CGO 编译失败
-
-SQLite 需要 CGO 支持。确保环境变量 `CGO_ENABLED=1`：
 
 ```bash
 export CGO_ENABLED=1
-```
-
-### Q: Go 模块下载慢？
-
-设置国内代理：
-
-```bash
 export GOPROXY=https://goproxy.cn,direct
 ```
 
-### Q: 端口被占用？
+### Go 模块下载慢
 
 ```bash
-./run.sh stop          # 先停止
+export GOPROXY=https://goproxy.cn,direct
-./run.sh start         # 再启动
+export GOTOOLCHAIN=local
-# 或强制释放端口
+```
+
+### 端口被占用
+
+```bash
+./run.sh stop
+# 或
 lsof -ti:8080 | xargs kill -9
 lsof -ti:5173 | xargs kill -9
 ```
+
+### Mac 编译的二进制无法在 Linux 运行
+
+`./run.sh build` 在 Mac 上产出 darwin 二进制。Linux 部署请使用：
+
+- `./run.sh release v1.x`（Docker 镜像）
+- 或在 Linux 服务器上执行 `./run.sh build`
+
+## 下一步
+
+- [部署指南](./deployment.md) — 生产环境、版本管理、K8s
+- [开发规范](./development-guide.md) — 代码规范
+- [API 接口](./api-reference.md) — 后端 API