docs

docs/developer/architecture.md

@@ -0,0 +1,42 @@
+# 系统架构
+
+CLICD 由 Go 后端、React 前端和宿主机虚拟化能力组成。
+
+## 后端
+
+后端入口在 `backend/main.go`，HTTP 服务路由集中在 `backend/internal/server/server.go`。主要模块：
+
+- `internal/api`：Web 面板和 `/api/v1` 的 HTTP 接口。
+- `internal/config`：配置和 SQLite 存储。
+- `internal/lxc`：LXC 容器管理。
+- `internal/kvm`：KVM/libvirt 虚拟机管理。
+- `internal/cli`：命令行管理入口。
+- `internal/server`：静态前端嵌入和 HTTP 服务。
+- `internal/version`：版本号。
+
+## 前端
+
+前端入口在 `frontend/src/main.tsx`，页面位于 `frontend/src/pages`，通用组件位于 `frontend/src/components`。
+
+主要页面：
+
+- 控制面板：`Dashboard.tsx`
+- 容器列表：`Containers.tsx`
+- 容器详情：`ContainerDetail.tsx`
+- 镜像管理：`ImageManagement.tsx`
+- 安全告警：`Security.tsx`
+- 快照管理：`Snapshots.tsx`
+- 路由管理：`Routing.tsx`
+- API 集成：`ApiIntegration.tsx`
+- 主机报告：`HostReport.tsx`
+- 子用户管理：`SubUserManagement.tsx`
+
+## 前端嵌入
+
+生产构建时，前端产物会放入 `backend/internal/server/web`，后端通过 Go embed 提供静态文件，并对非 API 路由返回 SPA 入口。
+
+## 接口分层
+
+- `/api/*`：Web 面板和兼容接口。
+- `/api/v1/*`：推荐给外部自动化系统使用的版本化接口。
+- WebSSH 和 WebVNC 使用短期票据后建立 WebSocket 连接。

docs/developer/build.md

@@ -0,0 +1,42 @@
+# 本地构建
+
+## 前端构建
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+构建输出位于 `frontend/dist`。
+
+## 后端构建
+
+```bash
+cd backend
+go test ./...
+go build -o ../build/clicd .
+```
+
+如果要打包嵌入式 Web 面板，需要先把前端构建产物同步到后端嵌入目录。
+
+## 一键构建
+
+项目根目录提供了构建脚本：
+
+```bash
+bash build.sh
+```
+
+该脚本用于串联前端构建、静态资源同步和 Go 二进制构建。
+
+## 文档站构建
+
+```bash
+cd docs
+npm install
+npm run dev
+npm run build
+```
+
+`npm run dev` 用于本地预览，`npm run build` 用于生成静态文档。

docs/developer/release.md

@@ -0,0 +1,44 @@
+# 发布流程
+
+CLICD 的安装和升级依赖 GitHub Release 产物。发布时建议使用语义化版本标签，例如 `v1.1.6`。
+
+## 版本号
+
+版本号需要同步检查：
+
+- `backend/internal/version/version.go`
+- `frontend/package.json`
+- Release 标签。
+
+## Release 产物
+
+安装脚本会优先下载 Linux AMD64 产物：
+
+```text
+clicd-linux-amd64.tar.gz
+```
+
+在部分场景中也会尝试下载单独二进制：
+
+```text
+clicd-linux-amd64
+```
+
+## 安装脚本行为
+
+- `CLICD_VERSION=latest`：使用 GitHub `releases/latest`。
+- `CLICD_VERSION=vX.Y.Z`：下载指定标签的 Release 产物。
+
+示例：
+
+```bash
+CLICD_VERSION=v1.1.6 sh install.sh
+```
+
+## 发布后验证
+
+- 安装脚本可以下载新版本。
+- `systemctl status clicd` 正常。
+- `/api/version` 返回新版本。
+- Web 面板可以加载前端资源。
+- 容器列表、任务队列、API Key 页面可以正常打开。