docs: initial FCP documentation and GitHub Actions deploy

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 1ssqq1lxr

.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+name: 部署到 GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: 构建 Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'npm'
+
+      - name: 安装依赖
+        run: npm install
+
+      - name: 构建网站
+        run: npm run build
+
+      - name: 上传构建制品
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    name: 部署到 GitHub Pages
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: 部署到 GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,16 @@
+# Dependencies
+/node_modules
+# Production
+/build
+# Generated files
+.docusaurus
+.cache-loader
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -0,0 +1,67 @@
+# FCP 产品文档
+
+FCP（FluxMQ Control Plane）产品文档站点，基于 Docusaurus 构建。
+
+## 本地开发
+
+```bash
+npm install
+npm run start
+```
+
+访问 http://localhost:3000
+
+## 构建
+
+```bash
+npm run build
+npm run serve  # 预览构建结果
+```
+
+## GitHub Actions 与 Pages 部署
+
+推送代码到 `main` 分支后，GitHub Actions 会自动构建并部署到 GitHub Pages。
+
+**首次使用需在仓库设置中开启 Pages：**
+
+1. 打开 [quickmsg/fcp-doc](https://github.com/quickmsg/fcp-doc) → **Settings** → **Pages**
+2. **Source** 选择 **GitHub Actions**
+3. 保存后，每次推送到 `main` 会触发 `.github/workflows/deploy.yml`，构建 Docusaurus 并部署
+
+部署完成后访问：`https://quickmsg.github.io/fcp-doc/`（若未配置自定义域名）。
+
+## 文档结构
+
+- **产品介绍**：FCP 定位、功能、与 FluxMQ 关系
+- **安装部署**：Linux 安装包、Docker、配置说明
+- **配置说明**：config.toml 配置项
+- **功能指南**：应用、License、项目、组织、用户、代理、监控、告警、审计
+- **API 概览**：REST API 与认证说明
+- **FAQ**：常见问题
+
+## 作为 Git 子模块使用
+
+在 FluxMQ 主仓库中添加 FCP 文档子模块（需先在 GitHub 创建仓库 `quickmsg/fcp-doc`）：
+
+```bash
+# 1. 在 fcp-doc 目录初始化并推送到远程（首次）
+cd fcp-doc
+git init
+git add .
+git commit -m "docs: initial FCP documentation"
+git branch -M main
+git remote add origin git@github.com:quickmsg/fcp-doc.git
+git push -u origin main
+
+# 2. 在 fluxmq 根目录添加子模块（若 fcp-doc 目录已存在且含未提交内容，可先备份后删除再执行）
+cd /path/to/fluxmq
+git submodule add git@github.com:quickmsg/fcp-doc.git fcp-doc
+```
+
+克隆主仓库时拉取子模块：
+
+```bash
+git clone --recurse-submodules git@github.com:quickmsg/fluxmq.git
+# 或已克隆后
+git submodule update --init --recursive
+```

docs/FAQ.md

@@ -0,0 +1,39 @@
+# 常见问题
+
+## 安装与部署
+
+**Q: 支持哪些数据库？**  
+A: PostgreSQL 13+、MySQL 8.0+、SQLite 3.x。生产环境建议使用 PostgreSQL 或 MySQL。
+
+**Q: 首次登录账号从哪里来？**  
+A: 若配置中 `admin.auto_create = true`，首次启动时会根据 `admin` 节创建管理员账号。否则需通过迁移或脚本创建。
+
+**Q: 代理端口 8081 无法访问？**  
+A: 检查 config.toml 中 `[proxy]` 的 host/port，以及防火墙、安全组是否放行该端口。
+
+## License 与 FluxMQ
+
+**Q: FluxMQ 如何切换到 FCP 模式？**  
+A: 在 FluxMQ 的 config.yaml 中设置 `license.mode: FCP`，并配置 `proxy.serverUrl`、`proxy.token`、`proxy.applicationId`，指向 FCP 及在 FCP 中创建的应用。
+
+**Q: FCP 中应用与 FluxMQ 的对应关系？**  
+A: 一个 FCP 应用可对应多台 FluxMQ 节点（同一业务集群）。每台节点配置相同的 applicationId 与对应 token。
+
+**Q: Token 泄露怎么办？**  
+A: 在 FCP 应用管理中重新生成或更换 Proxy Token，并更新所有 FluxMQ 节点的 config.yaml 后重启。
+
+## 权限与多租户
+
+**Q: 如何限制某用户只能看某个项目？**  
+A: 将用户角色设为项目管理员或普通用户，并只分配至对应项目，即可实现按项目隔离。
+
+**Q: 审计日志保留多久？**  
+A: 以实际实现与配置为准，可在配置或数据库中设置保留策略。
+
+## 监控与告警
+
+**Q: 告警不触发？**  
+A: 检查告警规则条件是否满足、规则是否启用，以及通知渠道是否配置正确且可用。
+
+**Q: 支持哪些通知渠道？**  
+A: 常见为钉钉、飞书、企业微信等，以 FCP 当前实现为准，在「通知渠道」中配置。

docs/api/overview.md

@@ -0,0 +1,28 @@
+# API 概览
+
+FCP 提供 REST API，供前端与第三方系统集成。
+
+## 认证
+
+- 登录：`POST /api/v1/auth/login`，请求体含 `username`、`password`，返回 JWT。
+- 获取当前用户：`GET /api/v1/auth/me`，Header 需带 `Authorization: Bearer <token>`。
+- 其他接口均在 Header 中携带上述 Token。
+
+## 主要模块
+
+| 模块 | 路径前缀 | 说明 |
+|------|----------|------|
+| 认证 | /api/v1/auth | 登录、当前用户 |
+| 组织 | /api/v1/organizations | 组织 CRUD |
+| 项目 | /api/v1/projects | 项目 CRUD |
+| 应用 | /api/v1/applications | 应用 CRUD（以实际路由为准） |
+| License | /api/v1/licenses | License 管理（以实际路由为准） |
+| 告警 | /api/v1/alerts | 告警列表与状态更新 |
+| 告警规则 | /api/v1/alert-rules | 告警规则 CRUD |
+| 通知渠道 | /api/v1/notification-channels | 通知渠道配置（以实际路由为准） |
+| 审计 | /api/v1/audit-logs | 审计日志查询 |
+
+## 说明
+
+- 实际路径与请求/响应格式以 fmq-admin 代码与 OpenAPI 文档为准。
+- 更多接口可参考 [fmq-admin README](https://github.com/quickmsg/fmq-admin) 中的 API 章节。

docs/config/read.md

@@ -0,0 +1,62 @@
+# 配置说明
+
+FCP 使用 **config.toml** 作为主配置文件（部分部署方式支持环境变量覆盖）。
+
+## 配置示例
+
+```toml
+[server]
+address = "0.0.0.0:8080"
+
+[database]
+type = "sqlite"
+url = "/opt/fcp-admin/data/data.db"
+
+[jwt]
+secret = "your-jwt-secret-key"
+expiration = 86400
+
+[admin]
+username = "admin"
+password = "admin"
+email = "admin@example.com"
+auto_create = true
+
+[logging]
+level = "info"
+file_dir = "logs"
+
+[proxy]
+host = "0.0.0.0"
+port = 8081
+```
+
+## 配置项说明
+
+| 节 | 配置项 | 说明 |
+|----|--------|------|
+| server | address | 服务监听地址，如 `0.0.0.0:8080` |
+| database | type | 数据库类型：postgres / mysql / sqlite |
+| database | url | 数据库连接 URL |
+| jwt | secret | JWT 签名密钥，生产环境务必修改 |
+| jwt | expiration | Token 有效期（秒） |
+| admin | username / password / email | 初始管理员账号（auto_create 时创建） |
+| admin | auto_create | 是否自动创建管理员 |
+| logging | level | 日志级别：debug / info / warn / error |
+| logging | file_dir | 日志目录 |
+| proxy | host / port | 代理服务监听地址与端口，供 FluxMQ FCP 模式连接 |
+
+## 数据库 URL 示例
+
+```bash
+# PostgreSQL
+url = "postgres://user:password@localhost:5432/fcp_admin"
+
+# MySQL
+url = "mysql://user:password@localhost:3306/fcp_admin"
+
+# SQLite
+url = "sqlite:./data/fcp_admin.db"
+```
+
+修改配置后需重启 FCP 服务。

docs/guide/alerts.md

@@ -0,0 +1,27 @@
+# 告警管理
+
+FCP 支持告警规则与告警记录，并可对接多种通知渠道。
+
+## 告警规则
+
+- **创建规则**：在 **告警规则** 中配置触发条件（如连接数超限、节点离线等）。
+- **严重程度**：可设置多级严重程度，便于分级处理。
+- **关联对象**：规则可关联到应用、集群或全局。
+
+## 告警记录
+
+- **告警列表**：查看历史告警及状态（未处理/已处理/已忽略）。
+- **状态更新**：对单条告警进行确认、处理或忽略。
+
+## 通知渠道
+
+- 在 **通知渠道** 中配置钉钉、飞书、企业微信等，用于接收告警通知。
+- 告警触发后，FCP 按规则将消息推送到已配置的渠道。
+
+## API 示例
+
+- 获取告警列表：`GET /api/v1/alerts`
+- 更新告警状态：`PUT /api/v1/alerts/:id`
+- 告警规则 CRUD：`/api/v1/alert-rules`
+
+具体路径与请求体以实际 API 文档为准。

docs/guide/applications.md

@@ -0,0 +1,30 @@
+# 应用管理
+
+应用（Application）是 FCP 中管理 FluxMQ 集群的基本单元，对应一个或多个 FluxMQ 节点。
+
+## 概念
+
+- **应用**：代表一套 FluxMQ 业务集群，用于 License 分配、代理与监控。
+- **应用类型**：如 FluxMQ；后续可扩展其他类型。
+- **License 激活方式**：本地文件（LOCAL）或通过 FCP 激活（FCP 模式）。
+
+## 创建应用
+
+1. 登录 FCP 控制台。
+2. 进入 **应用管理**（或「应用」菜单）。
+3. 点击 **新建应用**，填写：
+   - 应用名称
+   - 所属项目
+   - 应用类型（如 FluxMQ）
+   - License 激活方式（FCP 时需在本应用下分配 License）
+   - 可选：监控采集间隔、数据保留天数等。
+
+## 代理与连接
+
+- **代理模式**：当 FluxMQ 使用 FCP 模式时，需在 FCP 中为该应用配置 **Proxy Token**、**代理端口** 等。
+- FluxMQ 端在 `config.yaml` 中配置 `proxy.serverUrl`、`proxy.token`、`proxy.applicationId`，指向本 FCP 及对应应用。
+
+## 监控
+
+- 可为应用配置监控采集间隔；FCP 从 FluxMQ 节点拉取指标并展示。
+- 在 **监控** 或 **应用详情** 中查看连接数、消息量等。

docs/guide/audit.md

@@ -0,0 +1,22 @@
+# 操作审计
+
+FCP 记录用户关键操作，便于安全审计与问题追溯。
+
+## 审计内容
+
+- 登录/登出
+- 组织、项目、应用、用户、License 等资源的创建、修改、删除
+- 告警规则与通知渠道的变更
+- 其他敏感操作（以实际实现为准）
+
+## 查看审计日志
+
+- **系统管理员**：可查看全部审计日志。
+- **组织/项目管理员**：通常仅可查看本组织/项目相关操作（以权限设计为准）。
+
+在 **审计日志** 页面可按时间、用户、操作类型等筛选查询。
+
+## API
+
+- 获取审计日志：`GET /api/v1/audit-logs`
+- 支持分页与筛选参数，具体见 API 文档。

docs/guide/licenses.md

@@ -0,0 +1,27 @@
+# License 管理
+
+FCP 负责 FluxMQ 在 **FCP 模式** 下的 License 签发、分配与激活。
+
+## 两种 License 模式（FluxMQ 侧）
+
+| 模式 | 说明 |
+|------|------|
+| **LOCAL** | FluxMQ 使用本地 license 文件，不依赖 FCP。 |
+| **FCP** | FluxMQ 通过 FCP 进行 License 校验与拉取，需在 FCP 中创建应用并分配 License。 |
+
+## 在 FCP 中管理 License
+
+1. **签发/导入 License**  
+   系统管理员在 FCP 中上传或签发 License（具体以产品实现为准）。
+
+2. **分配到应用**  
+   将 License 分配到指定应用（Application），并设置连接数等限制。
+
+3. **FluxMQ 激活**  
+   - FluxMQ 配置 `license.mode: FCP` 和 `proxy.*`（serverUrl、token、applicationId）。
+   - 启动后向 FCP 发起激活请求，FCP 校验通过后下发 License 信息。
+
+## 连接数限制
+
+- 每个 License 可设置最大连接数等限制。
+- FCP 按应用维度统计连接并校验是否超限，超限时可按策略拒绝或告警。