[文档] 文档更新

.github/workflows/docker-image.yml

@@ -13,7 +13,18 @@ permissions:
 
 jobs:
   build:
-    runs-on: ubuntu-24.04
+    name: Build (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04
+          - arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -22,12 +33,11 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Set lowercase image name
+      - name: Set image metadata
-        id: meta
         shell: bash
         run: |
-          echo "image=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+          echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
-          echo "version=$(git describe --tags)" >> "$GITHUB_OUTPUT"
+          echo "VERSION=$(git describe --tags)" >> "$GITHUB_ENV"
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -45,19 +55,79 @@ jobs:
         with:
           context: ./atsf_server
           file: ./atsf_server/Dockerfile
-          push: true
+          platforms: ${{ matrix.platform }}
-          tags: |
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
-            ${{ steps.meta.outputs.image }}:${{ steps.meta.outputs.version }}
-            ${{ steps.meta.outputs.image }}:latest
           build-args: |
-            VERSION=${{ steps.meta.outputs.version }}
+            VERSION=${{ env.VERSION }}
-          cache-from: type=gha
+          cache-from: type=gha,scope=docker-${{ matrix.arch }}
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max,scope=docker-${{ matrix.arch }}
-          platforms: linux/amd64,linux/arm64
+
+      - name: Export digest
+        shell: bash
+        run: |
+          mkdir -p /tmp/digests
+          touch "/tmp/digests/${DIGEST#sha256:}"
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
 
       - name: Generate artifact attestation
         uses: actions/attest-build-provenance@v3
         with:
-          subject-name: ${{ steps.meta.outputs.image }}
+          subject-name: ${{ env.IMAGE }}
           subject-digest: ${{ steps.build.outputs.digest }}
           push-to-registry: true
+
+  merge:
+    name: Merge multi-arch manifest
+    runs-on: ubuntu-24.04
+    needs: build
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set image metadata
+        shell: bash
+        run: |
+          echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
+          echo "VERSION=$(git describe --tags)" >> "$GITHUB_ENV"
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push manifest list
+        working-directory: /tmp/digests
+        shell: bash
+        run: |
+          docker buildx imagetools create \
+            -t "${IMAGE}:${VERSION}" \
+            -t "${IMAGE}:latest" \
+            $(printf '%s@sha256:%s ' "${IMAGE}" *)
+
+      - name: Inspect image
+        run: docker buildx imagetools inspect "${IMAGE}:${VERSION}"

README.md

@@ -2,17 +2,12 @@
   <strong>中文</strong> | <a href="./README.en.md">English</a>
 </p>
 
-[//]: # (<p align="center">)
-
-[//]: # (  <a href="https://github.com/Rain-kl/ATSFlare"><img src="https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/atsf_server/web/public/logo.png" width="150" height="150" alt="ATSFlare logo"></a>)
-
-[//]: # (</p>)
-
 <div align="center">
+  <img src="./atsf_server/web/public/logo.png" width="120" height="120" alt="ATSFlare logo">
 
 # ATSFlare
 
-_✨ control plane for reverse proxy management ✨_
+轻量、自托管的反向代理控制面，用于管理 Nginx 配置发布、节点同步、TLS 证书与版本回滚。
 
 </div>
 
@@ -23,42 +18,91 @@ _✨ control plane for reverse proxy management ✨_
   <a href="https://github.com/Rain-kl/ATSFlare/releases/latest">
     <img src="https://img.shields.io/github/v/release/Rain-kl/ATSFlare?color=brightgreen&include_prereleases" alt="release">
   </a>
-  <a href="https://github.com/Rain-kl/ATSFlare/releases/latest">
+  <a href="https://github.com/Rain-kl/ATSFlare/pkgs/container/atsflare">
-    <img src="https://img.shields.io/github/downloads/Rain-kl/ATSFlare/total?color=brightgreen&include_prereleases" alt="release">
+    <img src="https://img.shields.io/badge/GHCR-ghcr.io%2Frain--kl%2Fatsflare-brightgreen" alt="ghcr">
   </a>
   <a href="https://goreportcard.com/report/github.com/Rain-kl/ATSFlare">
     <img src="https://goreportcard.com/badge/github.com/Rain-kl/ATSFlare" alt="GoReportCard">
   </a>
 </p>
 
-[//]: # (<p align="center">)
+## 项目定位
 
-[//]: # (  <a href="https://github.com/Rain-kl/ATSFlare/releases">Download</a>)
+ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
 
-[//]: # (  ·)
+它解决的是一套更直接的运维问题：
 
-[//]: # (  <a href="https://github.com/Rain-kl/ATSFlare/blob/main/README.en.md#deployment">Tutorial</a>)
+* 在管理端维护域名到源站的反代规则
+* 生成完整 Nginx 配置并发布激活版本
+* 让节点侧 Agent 自动拉取、校验、reload 与失败回滚
+* 托管 TLS 证书、管理节点与版本状态
+* 用更统一的 Web UI 完成日常运维操作
 
-[//]: # (  ·)
+当前明确不做多租户、复杂缓存平台、对象存储依赖、灰度分组发布等平台化扩展。详细边界见 [docs/design.md](./docs/design.md)。
 
-[//]: # (  <a href="https://github.com/Rain-kl/ATSFlare/issues">Feedback</a>)
+## 核心能力
 
-[//]: # (</p>)
+* 反向代理规则管理：一个域名对应一个源站地址，统一维护、统一发布
+* 配置版本化：支持预览、发布、激活、历史回滚，版本不可变
+* 节点接入：支持全局 `discovery_token` 首次接入，也支持节点专属 `agent_token`
+* Agent 自动应用：周期性同步、落盘、`nginx -t`、`nginx -s reload`、失败自动回滚
+* TLS 与域名管理：支持证书托管、域名资产维护、精确匹配与通配符匹配
+* 运维能力：配置变更摘要、Agent 运行参数下发、Agent 自更新、Server 自升级
+* 管理端 UI：基于 Next.js App Router + React 19 + Tailwind CSS 4 的新版前端
 
+## 界面预览
 
+以下图片当前为占位文件，后续你可以直接替换同名文件：
+
+* `docs/assets/readme/dashboard-overview.svg`
+* `docs/assets/readme/node-detail.svg`
+* `docs/assets/readme/version-release.svg`
+
+### 仪表盘总览
+
+![ATSFlare dashboard overview](./docs/assets/readme/dashboard-overview.png)
+
+### 节点详情与安装命令
+
+![ATSFlare node detail](./docs/assets/readme/node-detail.png)
+
+### 配置发布与版本管理
+
+![ATSFlare version release](./docs/assets/readme/version-release.png)
+
+## 系统架构
+
+```text
+ATSFlare Server (Gin + GORM + SQLite + Web UI)
+        |
+        | HTTP API / Config Pull
+        v
+ATSFlare Agent (register / heartbeat / sync / apply / update)
+        |
+        v
+Local Nginx or Docker Nginx
+        |
+        v
+Origin
+```
+
+职责划分：
+
+* `atsf_server`：管理端 UI、管理 API、Agent API、配置渲染、发布与激活、状态存储
+* `atsf_agent`：节点注册、心跳、同步、本地文件写入、Nginx 校验、reload、回滚、自更新
+* `atsf_server/web`：新版管理端前端，静态导出后由 Go Server 托管
 
 ## 仓库结构
 
-- `atsf_server`: Gin + GORM + SQLite 的控制中心，包含管理端 API、Agent API 和 Web 管理台
+* `atsf_server`：Gin + GORM + SQLite 单体控制面
-- `atsf_agent`: Go 单体 Agent，负责注册、心跳、同步配置、写入 Nginx 路由文件并 reload
+* `atsf_server/web`：Next.js 15 App Router 管理端前端
-- `docs`: 设计、开发规范、开发计划和部署联调文档
+* `atsf_agent`：Go 单体 Agent
-
+* `scripts`：安装脚本与辅助脚本
+* `docs`：设计、开发规范、部署、配置项等文档
 
 ## 快速开始
 
-### 1. 启动 Server
+### 1. 通过 Docker Compose 启动 Server
-
-可直接使用 GHCR 镜像通过 Docker Compose 启动控制面：
 
 ```yaml
 services:
@@ -72,6 +116,7 @@ services:
       SESSION_SECRET: replace-with-random-string
       SQLITE_PATH: /data/atsflare.db
       GIN_MODE: release
+      PORT: "3000"
     volumes:
       - atsflare-data:/data
 
@@ -83,14 +128,16 @@ volumes:
 docker compose up -d
 ```
 
-默认访问地址：`http://localhost:3000`。
+访问地址：`http://localhost:3000`
 
-- [docs/deployment.md](./docs/deployment.md)
+默认账号：
 
+* 用户名：`root`
+* 密码：`123456`
 
-### 2. 使用 Discovery Token 一键部署 Agent
+### 2. 使用 Discovery Token 一键接入 Agent
 
-适用于新节点首次接入，Agent 会使用全局 `discovery_token` 自动注册并换取节点专属 `agent_token`。
+适用于新节点首次接入，Agent 会自动注册并换取节点专属 `agent_token`。
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
@@ -98,7 +145,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/insta
   --discovery-token YOUR_DISCOVERY_TOKEN
 ```
 
-### 3. 使用 Agent Token 一键部署 Agent
+### 3. 使用 Agent Token 一键接入 Agent
 
 适用于已经在管理端预创建节点、并拿到节点专属 `agent_token` 的场景。
 
@@ -111,12 +158,24 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/insta
 说明：
 
 * `--server-url` 替换为实际控制面地址，例如 `http://192.168.1.10:3000`
-* Linux 默认安装到 `/opt/atsflare-agent`，并创建 `atsflare-agent` systemd 服务
+* 默认安装目录为 `/opt/atsflare-agent`
-* 重复执行相同命令可用于升级 Agent 到最新 Release
+* 脚本会创建 `atsflare-agent.service` 并启动 systemd 服务
-* Root 用户可在管理端顶栏点击“版本”检查最新 Release，并在 Release 二进制部署场景下直接触发 Server 自升级
+* 重复执行安装命令可用于升级 Agent 到最新 Release
 
+## 典型使用流程
 
-## 部署说明
+1. 启动 Server 并登录管理端
+2. 新增或编辑反代规则
+3. 预览配置或查看变更摘要
+4. 发布并激活新的配置版本
+5. Agent 在后续同步中拉取激活版本
+6. Agent 本地执行 `nginx -t`
+7. 校验成功后执行 `nginx -s reload`
+8. 若失败则自动回滚并上报最终结果
+
+版本号格式固定为 `YYYYMMDD-NNN`，历史版本不可变，回滚通过重新激活旧版本实现。
+
+## 部署与交付
 
 当前仓库的交付形式：
 
@@ -124,23 +183,119 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/insta
 * Server Docker 镜像发布到 GitHub Container Registry：`ghcr.io/rain-kl/atsflare`
 * Agent 二进制发布到 GitHub Releases
 
-详细文档：
+Docker 镜像工作流仅构建 `atsf_server`，并产出 `linux/amd64` 与 `linux/arm64` 多架构镜像。
 
-* [docs/deployment.md](./docs/deployment.md)
+## 常用配置
-* [docs/design.md](./docs/design.md)
 
+### Server 环境变量
 
-## 贡献
+| 环境变量 | 作用 | 默认值 |
+| --- | --- | --- |
+| `PORT` | Server 监听端口 | `3000` |
+| `GIN_MODE` | Gin 运行模式 | 非 `debug` 时按 release |
+| `SESSION_SECRET` | Session 签名密钥 | 启动时随机生成 |
+| `SQLITE_PATH` | SQLite 数据库文件路径 | `atsflare.db` |
+| `SQL_DSN` | MySQL DSN，设置后优先于 SQLite | 空 |
+| `UPLOAD_PATH` | 上传目录 | `upload` |
 
-参与开发请先阅读：
+### 前端构建变量
+
+| 环境变量 | 作用 | 默认值 |
+| --- | --- | --- |
+| `NEXT_PUBLIC_API_BASE_URL` | 前端请求 API 的基础路径 | `/api` |
+| `NEXT_PUBLIC_APP_VERSION` | 前端展示版本号 | `dev` |
+
+### Agent 核心配置
+
+| 字段 | 作用 |
+| --- | --- |
+| `server_url` | 控制面地址 |
+| `agent_token` | 节点专属认证 Token |
+| `discovery_token` | 首次自动注册使用的全局 Token |
+| `data_dir` | Agent 托管数据目录 |
+| `nginx_path` | 本机 Nginx 路径，设置后走本机模式 |
+| `nginx_container_name` | Docker 模式下的 Nginx 容器名 |
+
+完整配置项说明见 [docs/app-config.md](./docs/app-config.md)。
+
+## 本地开发
+
+### Server
+
+```bash
+cd atsf_server
+export SESSION_SECRET='replace-with-random-string'
+export SQLITE_PATH='./atsflare.db'
+go run .
+```
+
+### Frontend
+
+```bash
+cd atsf_server/web
+corepack enable
+pnpm install
+pnpm build
+```
+
+### Agent
+
+```bash
+cd atsf_agent
+go run ./cmd/agent -config /path/to/agent.json
+```
+
+### 常用验证命令
+
+```bash
+cd atsf_server
+GOCACHE=/tmp/atsflare-go-cache go test ./...
+```
+
+```bash
+cd atsf_agent
+GOCACHE=/tmp/atsflare-go-cache go test ./...
+```
+
+## 文档导航
+
+建议按以下顺序阅读：
 
 1. [docs/design.md](./docs/design.md)
 2. [docs/development-guidelines.md](./docs/development-guidelines.md)
 3. [docs/development-plan.md](./docs/development-plan.md)
+4. [docs/frontend-revamp-plan.md](./docs/frontend-revamp-plan.md)
+5. [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md)
+6. [docs/deployment.md](./docs/deployment.md)
+7. [docs/app-config.md](./docs/app-config.md)
 
-前端开发补充：
+## 管理端与接口
 
-* 新版管理端位于 `atsf_server/web`
+管理端当前覆盖：
-* 前端包管理器统一使用 `pnpm`
-* 构建命令为 `pnpm build`，产物输出到 `atsf_server/web/build`
 
+* 反代规则
+* 配置版本
+* 节点管理
+* 应用记录
+* TLS 证书
+* 域名管理
+* 用户管理
+* 设置
+* 版本更新
+
+登录管理端后，可访问 Swagger UI：`/swagger/index.html`
+
+## 贡献开发
+
+参与开发前请先阅读：
+
+* [docs/design.md](./docs/design.md)
+* [docs/development-guidelines.md](./docs/development-guidelines.md)
+* [docs/frontend-development-guidelines.md](./docs/frontend-development-guidelines.md)
+
+约束摘要：
+
+* 超出设计边界的改动，先更新设计文档再编码
+* Server 继续保持单体结构，不为简单需求引入额外基础设施
+* 前端统一位于 `atsf_server/web`，请求层统一收敛到 `lib/api/`
+* 新代码默认遵循当前正式基线，不回退到旧版 CRA / Semantic UI 结构

docs/deployment.md

@@ -280,7 +280,7 @@ Docker 镜像发布使用 [.github/workflows/docker-image.yml](.github/workflows
 
 * 仅构建 `atsf_server` 服务端镜像
 * 发布到 GitHub Container Registry（`ghcr.io/<owner>/<repo>:<tag>`）
-* 单个工作流同时产出 `linux/amd64` 与 `linux/arm64` 多架构镜像
+* 单个工作流通过分架构原生构建再合并 manifest 的方式产出 `linux/amd64` 与 `linux/arm64` 多架构镜像，避免 `arm64` 长时间模拟编译
 
 ---