ai-workspace-services/accounts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add full documentation outline

Browse Source
This commit is contained in:
Haitao Pan 2026-01-26 22:21:11 +08:00
parent 3ce371658a
commit ccdf676ae9
38 changed files with 1150 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/README.md Normal file
View File

@ -0,0 +1,26 @@
# XControl Account Service 文档
本文档集覆盖 `accounts.svc.plus` 账号服务的安装、配置、使用、架构、运维与贡献指南。内容基于当前代码与配置模板整理，便于在不同环境快速落地。
## 快速入口
- 新手：`getting-started/introduction.md`、`getting-started/quickstart.md`
- 架构：`architecture/overview.md`、`architecture/components.md`
- 配置与使用：`usage/config.md`、`usage/deployment.md`、`usage/examples.md`
- API：`api/overview.md`、`api/endpoints.md`、`api/errors.md`
- 运维：`operations/monitoring.md`、`operations/troubleshooting.md`
## 文档结构
- `getting-started/`：10 分钟跑起来
- `architecture/`：Why > How 的架构说明
- `usage/`：如何配置与使用
- `api/`：接口说明与错误约定
- `integrations/`：数据库、云、邮件与第三方对接
- `advanced/`：性能、安全、扩展
- `development/`：开发与贡献
- `operations/`：监控、日志、备份与排障
- `governance/`：许可证与发布流程
- `appendix/`：FAQ、术语表与参考资料
> 备注：仓库内已有 `docs/SMTP_GMAIL_SETUP.md`（Cloud Run + Gmail SMTP），在 `integrations/cloud.md` 中有交叉引用。

26
docs/advanced/customization.md Normal file
View File

@ -0,0 +1,26 @@
# 二次开发与定制
## 配置模板
- `config/*.yaml` 可作为环境模板
- 容器中可通过 `CONFIG_TEMPLATE` + `envsubst` 渲染
## 自定义 Xray 模板
- 设置 `xray.sync.templatePath`
- 模板必须包含 `inbounds[0].settings.clients` 数组
## 扩展存储
- 实现 `internal/store.Store` 接口
- 在 `store.New` 中注册新驱动
## 邮件发送
- SMTP 逻辑集中在 `internal/mailer`
- 可替换为 API 驱动（SendGrid 等）
## API 扩展
- 路由集中于 `api/` 与 `cmd/accountsvc/main.go`
- 建议保持统一错误结构

24
docs/advanced/performance.md Normal file
View File

@ -0,0 +1,24 @@
# 性能与扩展性
## 数据库连接池
配置项：
- `store.maxOpenConns`
- `store.maxIdleConns`
合理设置以避免数据库过载或连接不足。
## 会话存储
- 当前会话保存在进程内存
- 高并发或多实例场景建议外部化（未来可扩展）
## Xray 同步
- `xray.sync.interval` 控制同步频率
- 同步过于频繁会增加 I/O 与重启开销
## 日志级别
- `log.level` 支持 `debug|info|warn|error`
- 生产环境建议使用 `info` 或 `warn`

17
docs/advanced/scalability.md Normal file
View File

@ -0,0 +1,17 @@
# 高可用与水平扩展
## 当前限制
- 会话存储在内存中，无法在多实例间共享
- 多实例部署会导致用户在不同实例间会话失效
## 建议方向
- 引入集中式会话存储（如 Redis）
- API 层保持无状态，通过负载均衡扩展
- 数据库采用主从或 pglogical 多主架构
## Agent 扩展
- Controller 通过配置 `agents.credentials` 支持多 Agent
- Agent 状态通过内存 Registry 维护

25
docs/advanced/security.md Normal file
View File

@ -0,0 +1,25 @@
# 安全模型
## 身份与凭证
- 密码使用 bcrypt 哈希
- MFA 使用 TOTP（6 位，30s 窗口）
- 会话 token 存在内存中
## TLS 与传输安全
- Server TLS 配置：`server.tls.*`
- SMTP TLS 配置：`smtp.tls.mode`
- Agent 访问支持 TLS 校验开关
## 访问控制
- 会话鉴权：`Authorization` 或 Cookie
- 管理接口需要管理员或运维角色
- Agent 使用预共享 token 验证
## 安全注意事项
- API 显式拒绝在 query 参数中传递敏感信息
- 生产环境请使用真实 SMTP 配置并妥善管理 secrets
- 建议限制 CORS `allowedOrigins`

40
docs/api/auth.md Normal file
View File

@ -0,0 +1,40 @@
# 认证与鉴权
## 会话认证（默认）
1) 登录 `POST /api/auth/login` 成功后返回：
- `token`：会话 token
- `expiresAt`
- `user`
2) 客户端后续请求携带：
- `Authorization: Bearer <session-token>` 或
- Cookie `xc_session=<session-token>`
## 邮件验证
- 发送验证码：`POST /api/auth/register/send`
- 验证并注册：`POST /api/auth/register/verify`
当 SMTP 未配置或使用示例域名时，邮箱验证会自动关闭。
## MFA（TOTP）
- 申请 secret：`POST /api/auth/mfa/totp/provision`
- 验证并启用：`POST /api/auth/mfa/totp/verify`
- 关闭 MFA：`POST /api/auth/mfa/disable`
登录接口在部分场景会返回 `mfaToken`，用于后续验证。
## JWT 令牌服务（可选）
启用 `auth.enable: true` 后提供：
- `POST /api/auth/token/exchange`：使用 `public_token` 换取 access/refresh
- `POST /api/auth/token/refresh`：刷新 access token
注意事项：
- `token/exchange` 需要调用方提供 `user_id/email/roles`
- 当前版本多数保护路由仍使用会话 token，JWT 仅作为中间件校验存在
- 若开启 JWT，中间件要求 `Authorization: Bearer <access-token>`，但业务逻辑仍可能需要会话 token
建议：若主要使用会话认证，请将 `auth.enable` 设为 `false`。

42
docs/api/endpoints.md Normal file
View File

@ -0,0 +1,42 @@
# 接口列表
## 公共
- `GET /healthz`：健康检查
## 账号认证（/api/auth）
- `POST /api/auth/register`：注册
- `POST /api/auth/register/send`：发送邮箱验证码
- `POST /api/auth/register/verify`：验证邮箱验证码
- `POST /api/auth/login`：登录
- `POST /api/auth/token/exchange`：public token 换取 access/refresh
- `POST /api/auth/token/refresh`：刷新 access token
### 需要会话（或受保护）
- `GET /api/auth/session`：获取当前会话用户
- `DELETE /api/auth/session`：注销
- `POST /api/auth/mfa/totp/provision`：申请 MFA TOTP secret
- `POST /api/auth/mfa/totp/verify`：验证 MFA TOTP
- `POST /api/auth/mfa/disable`：关闭 MFA
- `GET /api/auth/mfa/status`：查询 MFA 状态
- `POST /api/auth/password/reset`：发起密码重置（需要登录）
- `POST /api/auth/password/reset/confirm`：确认密码重置
- `GET /api/auth/subscriptions`：订阅列表
- `POST /api/auth/subscriptions`：订阅 upsert
- `POST /api/auth/subscriptions/cancel`：取消订阅
- `POST /api/auth/config/sync`：配置同步（当前返回未实现）
- `GET /api/auth/admin/settings`：获取权限矩阵
- `POST /api/auth/admin/settings`：更新权限矩阵
- `GET /api/auth/admin/users/metrics`：用户指标
- `GET /api/auth/admin/agents/status`：Agent 状态
> 说明：`/api/auth/admin/*` 需要管理员或运维角色。
## Agent API（/api/agent/v1）
- `GET /api/agent/v1/users`：获取 Xray 客户端列表
- `POST /api/agent/v1/status`：上报 Agent 状态
Agent 认证通过 `Authorization: Bearer <agent-token>`。

23
docs/api/errors.md Normal file
View File

@ -0,0 +1,23 @@
# 错误码约定
常见格式（多数接口）：
```json
{"error":"code","message":"human readable message"}
```
## 常见错误码（节选）
- `invalid_request`：请求体错误
- `missing_credentials` / `credentials_in_query`
- `invalid_email`
- `password_too_short`
- `email_already_exists` / `name_already_exists`
- `invalid_session` / `session_token_required`
- `mfa_code_required` / `invalid_mfa_code`
- `token_service_unavailable`
- `invalid_public_token` / `invalid_refresh_token`
- `subscription_not_found`
- `agent_status_unavailable`
少数接口仅返回 `{"error":"..."}`。具体返回以接口实现为准，可在 `api/` 中查阅。

19
docs/api/overview.md Normal file
View File

@ -0,0 +1,19 @@
# API 设计原则
- REST 风格 + JSON
- 大多数接口使用错误结构：`{"error":"code","message":"..."}`
- 少数接口直接返回 `{"error":"..."}`
- 默认以会话 token 作为认证方式
## 基础路径
- 健康检查：`GET /healthz`
- 用户 API：`/api/auth/*`
- Agent API：`/api/agent/v1/*`
## 认证方式
- 会话 token：`Authorization: Bearer <session-token>` 或 `xc_session` Cookie
- JWT（可选）：启用 `auth.enable` 后，对 `/api/auth/*` 保护路由增加 JWT 校验
> 注意：当前实现中，大部分保护路由仍依赖会话 token。若开启 JWT 中间件，需确保请求同时满足会话逻辑（详见 `api/auth.md` 的说明）。

13
docs/appendix/faq.md Normal file
View File

@ -0,0 +1,13 @@
# FAQ
## Q: 为什么注册不需要邮箱验证码？
A: 当 `smtp.host` 为空或使用 `*.example.com` 时，系统自动关闭邮件验证。
## Q: 会话为什么会丢失？
A: 会话存储在进程内存中，重启或多实例会导致失效。
## Q: 如何启用多区域同步？
A: 参见 `sql/readme.md`，可使用 pgsync 或 pglogical。
## Q: auth.enable 打开后无法访问接口？
A: JWT 中间件会生效，但多数接口仍依赖会话 token，请参考 `api/auth.md`。

10
docs/appendix/glossary.md Normal file
View File

@ -0,0 +1,10 @@
# 术语表
- Account Service：账号服务主程序
- Session：登录会话 token
- MFA：多因素认证（TOTP）
- Agent：部署在边缘节点的同步程序
- Controller：管理 Agent 的中心账号服务
- Xray：代理配置同步目标
- pgsync：逻辑导出/导入同步工具
- pglogical：PostgreSQL 逻辑复制扩展

7
docs/appendix/references.md Normal file
View File

@ -0,0 +1,7 @@
# 参考资料
- 配置模板：`config/`
- 数据库 Schema：`sql/schema.sql`
- 同步说明：`sql/readme.md`
- Cloud Run 示例：`deploy/gcp/cloud-run/service.yaml`
- SMTP Gmail 指南：`docs/SMTP_GMAIL_SETUP.md`

30
docs/architecture/components.md Normal file
View File

@ -0,0 +1,30 @@
# 组件职责边界
## 应用入口
- `cmd/accountsvc`：主服务入口（server/agent/server-agent）
- `cmd/createadmin`：创建/更新超级管理员
- `cmd/migratectl`：数据库迁移与导入导出
- `cmd/syncctl`：跨环境同步工具
## API 层
- `api/`：HTTP 路由、请求校验、响应与错误格式
- `api/admin_*`：管理员指标与 Agent 状态接口
## 认证与安全
- `internal/auth`：JWT 令牌服务与中间件
- `internal/store`：密码哈希与角色等级规范化
## 数据存储
- `internal/store`：Store 接口与内存/PostgreSQL 实现
- `sql/`：schema 与 pgsync/pglogical 相关脚本
## 邮件与通知
- `internal/mailer`：SMTP 发送器与 TLS 模式支持
## Xray 相关
- `internal/xrayconfig`：Xray 配置生成与同步
- `internal/agentmode`：Agent 控制循环（拉取用户、上报状态）
- `internal/agentserver`：Controller 侧 Agent 注册与状态管理
## 服务层
- `internal/service`：管理员权限矩阵与用户指标聚合

30
docs/architecture/design-decisions.md Normal file
View File

@ -0,0 +1,30 @@
# 关键设计取舍
## 会话存储为内存
- 优点：实现简单、无额外依赖
- 代价：重启丢失会话，无法横向扩展
## 主业务使用原生 SQL + pgx
- `internal/store/postgres.go` 使用 `database/sql` + pgx
- 优点：可控的 SQL 与更清晰的 schema 兼容逻辑
- 代价：代码量较高
## Admin Settings 使用 GORM
- 管理权限矩阵更新频率较低
- 使用 GORM 简化结构映射与事务处理
## 邮件验证与 SMTP 可选
- 未配置 SMTP 或使用示例域名时禁用验证
- 避免测试环境误发送邮件
## Agent 认证为预共享 Token
- 通过配置中的 token 哈希验证 Agent
- 适合私有网络与受控部署场景
## Xray 配置生成方式
- 定期从用户列表生成配置文件并原子写入
- 支持自定义模板与验证/重启命令
## JWT Token Service 作为可选能力
- 提供 public/access/refresh 机制
- 当前版本仍以会话 token 为主（详见 `api/auth.md`）

43
docs/architecture/overview.md Normal file
View File

@ -0,0 +1,43 @@
# 架构总览
Account Service 是一个单体 Go 服务，提供账号与运营相关能力，同时可作为 Xray Controller 管理 Agent。
## 逻辑架构（文字版）
```
Client
└─ HTTP API (Gin)
├─ Session / MFA / Email verification
├─ Subscription & Admin Settings
├─ Agent Controller (/api/agent/v1)
└─ Token Service (optional)
│
├─ Store (memory / postgres)
├─ Admin Settings DB (GORM, same DSN)
├─ SMTP Sender
└─ Xray Config Sync
```
## 核心数据流
1) 用户注册/登录
- API 校验输入 → Store 持久化用户 → 生成会话 token
- 可选：发送邮件验证码/密码重置邮件
2) 管理权限矩阵
- `admin_settings` 表保存模块与角色的开关
- 通过 GORM 读写，内置缓存避免频繁查询
3) Xray 同步（Controller + Agent）
- Controller: 暴露用户列表与 Agent 状态接口
- Agent: 定时拉取用户列表生成 Xray 配置，并上报状态
4) 数据同步
- `migratectl`：导入/导出 YAML 快照
- `syncctl`：通过 SSH 在不同环境间同步
## 关键边界
- 会话存储为进程内存（不可横向扩展）
- SMTP 未配置时自动关闭邮件验证
- JWT Token Service 为可选能力，需与会话机制配合使用

11
docs/architecture/roadmap.md Normal file
View File

@ -0,0 +1,11 @@
# Roadmap（可选）
以下为基于现状的可能演进方向，具体以实际需求为准：
- 会话外部化：引入 Redis 等持久化会话存储
- 认证统一：会话与 JWT 令牌机制整合
- API 描述：补充 OpenAPI/Swagger
- 监控指标：新增 Prometheus / OpenTelemetry 输出
- 插件化：订阅与支付渠道适配层
> 说明：以上方向尚未在当前代码中实现，仅供规划参考。

13
docs/development/code-structure.md Normal file
View File

@ -0,0 +1,13 @@
# 代码组织说明
- `cmd/`：可执行程序入口
- `api/`：HTTP 接口与业务控制层
- `internal/store/`：数据存储层（内存/PG）
- `internal/auth/`：JWT 令牌与鉴权中间件
- `internal/mailer/`：SMTP 邮件发送
- `internal/agentmode/`：Agent 模式实现
- `internal/agentserver/`：Controller 侧 Agent 管理
- `internal/xrayconfig/`：Xray 配置生成与同步
- `internal/service/`：管理员设置与指标聚合
- `sql/`：数据库 schema 与同步脚本
- `scripts/`：构建与运维脚本

12
docs/development/contributing.md Normal file
View File

@ -0,0 +1,12 @@
# 贡献指南
欢迎贡献本项目。建议流程：
1. 阅读 `docs/development/dev-setup.md`
2. 创建分支并保持提交粒度清晰
3. 运行 `go test ./...`
4. 确保文档与配置同步更新
如需调整数据库结构，请同步更新：
- `sql/schema.sql`
- 相关迁移与测试

26
docs/development/dev-setup.md Normal file
View File

@ -0,0 +1,26 @@
# 开发环境
## 依赖
- Go 1.25.1
- PostgreSQL（如使用 postgres store）
- 可选：`air` 热重载工具
## 初始化
```bash
make init-db
make build
```
## 运行
```bash
make start
# 或
make dev
```
## 热重载
`make dev` 会检测 `air`，未安装会提示安装链接。

17
docs/development/testing.md Normal file
View File

@ -0,0 +1,17 @@
# 测试策略
## 单元测试
```bash
make test
# 或
go test ./...
```
## 集成测试
```bash
make integration-test
```
集成测试会执行初始化与创建管理员流程，依赖本地数据库环境。

52
docs/getting-started/concepts.md Normal file
View File

@ -0,0 +1,52 @@
# 核心概念
以下概念来自当前代码与数据库结构，帮助理解账户服务的核心模型。
## 用户（User）
用户包含：
- `username` / `email` / `password`
- `role` 与 `level`：`admin` / `operator` / `user`
- `groups` / `permissions`
- MFA 状态（TOTP）与邮箱验证状态
## 会话（Session）
- 登录成功后产生会话 token
- 会话默认保存在进程内存（非持久化）
- 客户端可使用 `xc_session` Cookie 或 `Authorization: Bearer <token>`
## 邮件验证
- SMTP 未配置或使用 `*.example.com` 时自动关闭验证
- 启用后，注册需要邮箱验证码
## MFA（TOTP）
- 通过 `/api/auth/mfa/totp/provision` 生成 TOTP 秘钥
- 通过 `/api/auth/mfa/totp/verify` 完成验证并启用 MFA
- 可通过 `/api/auth/mfa/disable` 关闭
## 订阅（Subscription）
- 订阅信息保存在 `subscriptions` 表
- 支持 upsert 与 cancel
- 用于运营侧的订阅状态统计
## 管理权限矩阵（Admin Settings）
- 用于模块级权限开关
- 存储在 `admin_settings` 表
- 通过 `GET/POST /api/auth/admin/settings` 读取/更新
## Agent / Xray 同步
- Controller（账号服务）暴露 `/api/agent/v1` 接口
- Agent 定时拉取用户列表生成 Xray 配置
- Agent 上报健康状态供管理员查看
## 数据导入导出与同步
- `migratectl export/import`：YAML 快照导入导出
- `syncctl push/pull/mirror`：通过 SSH 进行跨环境同步
- `sql/` 下提供 pgsync 与 pglogical 同步脚本

58
docs/getting-started/installation.md Normal file
View File

@ -0,0 +1,58 @@
# 安装方式
本项目支持本地编译运行、Docker 容器运行，以及 Cloud Run 部署。以下步骤基于仓库现有脚本与配置。
## 本地安装（Go）
前置条件：
- Go 1.25.1（见 `go.mod`）
- PostgreSQL（若使用 `store.driver=postgres`）
编译与运行：
```bash
make build
./xcontrol-account --config config/account.yaml
```
或直接运行：
```bash
go run ./cmd/accountsvc/main.go --config config/account.yaml
```
## Docker
仓库包含多阶段 Dockerfile，运行时使用 `entrypoint.sh` 生成配置：
```bash
docker build -t accounts-svc-plus .
docker run --rm -p 8080:8080 \
-e CONFIG_TEMPLATE=/app/config/account.yaml \
-e CONFIG_PATH=/etc/xcontrol/account.yaml \
accounts-svc-plus
```
说明：
- `entrypoint.sh` 会将 `CONFIG_TEMPLATE` 通过 `envsubst` 渲染成 `CONFIG_PATH`
- 若设置了 `PORT` 环境变量，脚本会自动修改 `server.addr`
## Cloud Run
参考文件：
- `deploy/gcp/cloud-run/service.yaml`
- `deploy/gcp/cloud-run/stunnel.conf`
- `config/account.cloudrun.yaml`
构建与部署脚本：
```bash
GCP_PROJECT=your-project make cloudrun-build
GCP_PROJECT=your-project make cloudrun-deploy
```
Cloud Run 部署模板已包含：
- 主应用容器（Account API）
- Stunnel Sidecar（用于数据库安全隧道）
- SMTP Secret 环境变量注入示例

38
docs/getting-started/introduction.md Normal file
View File

@ -0,0 +1,38 @@
# 项目介绍
XControl Account Service（账号服务）负责用户注册、登录、会话管理、MFA、订阅状态与管理员权限矩阵等能力，同时提供与 Xray 节点协同的代理模式与跨区域数据同步工具。
## 解决的问题
- 统一账号体系：注册/登录/会话/密码重置
- 安全增强：邮件验证、TOTP 多因素认证
- 运营支持：订阅状态管理、用户指标统计
- 运维协同：Agent 模式同步 Xray 配置与状态
- 跨区数据：导入/导出与同步工具（`migratectl` / `syncctl`）
## 关键特性（基于当前代码）
- HTTP API：基于 Gin，默认端口 `:8080`，健康检查 `GET /healthz`
- 用户体系：用户名、邮箱、角色/等级、权限组
- 邮件能力：SMTP 可选；未配置 SMTP 时自动关闭邮件验证
- 会话管理：服务进程内存会话（非持久化）
- JWT 令牌服务：可选启用（public/access/refresh）
- 管理能力：管理员权限矩阵、用户指标与 Agent 状态接口
- Xray 侧同步：定期生成 Xray 配置并可触发校验/重启
## 运行模式
- `server`：仅启动账号 API 服务
- `agent`：仅启动 Agent，同步 Xray 配置并上报状态
- `server-agent` / `all` / `combined`：服务 + Agent 同时运行
## 代码位置速览
- 入口：`cmd/accountsvc/main.go`
- API：`api/`
- 配置：`config/`
- 数据库：`sql/`
- 工具：`cmd/migratectl`、`cmd/syncctl`、`cmd/createadmin`
- 运行脚本：`scripts/`
下一步：阅读 `getting-started/quickstart.md` 完成最小启动示例。

69
docs/getting-started/quickstart.md Normal file
View File

@ -0,0 +1,69 @@
# Quickstart（最小可运行示例）
以下步骤使用内存存储启动服务，适合本地快速验证 API 行为。
## 1. 准备最小配置
创建 `config/local.yaml`：
```yaml
mode: "server"
log:
level: info
server:
addr: ":8080"
store:
driver: "memory"
dsn: ""
session:
ttl: 24h
smtp:
host: ""
port: 587
username: ""
password: ""
from: ""
replyTo: ""
timeout: 10s
tls:
mode: "auto"
insecureSkipVerify: false
```
说明：
- `store.driver=memory` 可跳过数据库
- `smtp.host=""` 会关闭邮件验证
## 2. 启动服务
```bash
go run ./cmd/accountsvc/main.go --config config/local.yaml
```
## 3. 健康检查
```bash
curl http://localhost:8080/healthz
```
## 4. 注册与登录
```bash
# 注册
curl -X POST http://localhost:8080/api/auth/register \
-H 'Content-Type: application/json' \
-d '{"name":"demo","email":"demo@example.com","password":"Passw0rd!"}'
# 登录
curl -X POST http://localhost:8080/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"identifier":"demo@example.com","password":"Passw0rd!"}'
```
成功登录后返回 `token`，后续可使用：
```bash
curl -H 'Authorization: Bearer <session-token>' http://localhost:8080/api/auth/session
```
> 注意：会话保存在进程内存，重启服务会使会话失效。

5
docs/governance/license.md Normal file
View File

@ -0,0 +1,5 @@
# License
当前仓库未包含许可证文件（未检测到 `LICENSE`）。
如需开放或限制使用权限，请补充项目许可证并在此说明。

7
docs/governance/release-process.md Normal file
View File

@ -0,0 +1,7 @@
# 发布流程
当前仓库未定义正式发布流程。可以考虑：
- 使用 Git tag 标记版本
- 记录变更日志（CHANGELOG）
- 为生产部署准备固定镜像标签

7
docs/governance/security-policy.md Normal file
View File

@ -0,0 +1,7 @@
# 安全策略
当前仓库未定义正式的安全漏洞报告流程。
建议补充：
- 安全邮箱或工单入口
- 处理时限与披露策略

8
docs/integrations/ai-providers.md Normal file
View File

@ -0,0 +1,8 @@
# AI Providers
当前账号服务未集成任何 AI 模型或推理服务。
若未来需要对接 OpenAI / NVIDIA / OSS 模型，可在此文档补充：
- 鉴权方式
- 请求限流
- 费用与配额管理

24
docs/integrations/cloud.md Normal file
View File

@ -0,0 +1,24 @@
# 云部署与集成
## GCP Cloud Run
- 配置文件：`deploy/gcp/cloud-run/service.yaml`
- 配置模板：`config/account.cloudrun.yaml`
- 构建脚本：`scripts/cloudrun-build.sh`
- 部署脚本：`scripts/cloudrun-deploy.sh`
Cloud Run 模板包含 stunnel sidecar，用于连接数据库。
## Secrets 与环境变量
示例环境变量：
- `DB_HOST` / `DB_PORT` / `DB_NAME`
- `POSTGRES_USER` / `POSTGRES_PASSWORD`
- `SMTP_HOST` / `SMTP_PORT` / `SMTP_USERNAME` / `SMTP_PASSWORD`
## SMTP Gmail 参考
- 指南文件：`docs/SMTP_GMAIL_SETUP.md`
- 场景：Cloud Run + Gmail SMTP
> 若不需要邮件功能，直接置空 SMTP 配置即可。

29
docs/integrations/databases.md Normal file
View File

@ -0,0 +1,29 @@
# 数据库对接
## PostgreSQL
- 主业务存储使用 PostgreSQL（见 `internal/store/postgres.go`）
- Schema 位于 `sql/schema.sql`
- 迁移工具：`migratectl`
## 同步策略
仓库提供两类同步方式（见 `sql/readme.md`）：
1) pgsync（单向异步）
- 适合单主写入 + 异步同步
- 不需要超级用户权限
2) pglogical（双主最终一致）
- 适合多区域双写
- 需要安装 pglogical 扩展
## 常用命令
```bash
# 初始化 schema
go run ./cmd/migratectl/main.go migrate --dsn "$DB_URL"
# 校验 schema
go run ./cmd/migratectl/main.go verify --dsn "$DB_URL" --schema sql/schema.sql
```

17
docs/operations/backup.md Normal file
View File

@ -0,0 +1,17 @@
# 备份与恢复
## 逻辑备份（YAML）
```bash
migratectl export --dsn "$DB_URL" --output account-export.yaml
migratectl import --dsn "$DB_URL" --file account-export.yaml
```
## 数据库层备份
建议使用 PostgreSQL 原生命令：
```bash
pg_dump "$DB_URL" > account.dump
pg_restore -d "$DB_URL" account.dump
```

10
docs/operations/logging.md Normal file
View File

@ -0,0 +1,10 @@
# 日志
- 日志使用 `slog` 文本格式输出到 stdout
- 级别通过 `log.level` 控制（debug/info/warn/error）
示例：
```yaml
log:
level: info
```

9
docs/operations/monitoring.md Normal file
View File

@ -0,0 +1,9 @@
# 监控
当前服务提供以下监控入口：
- `GET /healthz`：存活检查
- `GET /api/auth/admin/users/metrics`：用户指标（需管理员）
- 日志输出：stdout
暂未提供 Prometheus/OpenTelemetry 指标，需要时可在此扩展。

28
docs/operations/troubleshooting.md Normal file
View File

@ -0,0 +1,28 @@
# 常见问题排查
## 登录成功后提示 session invalid
- 会话存储在内存中，重启服务会导致失效
- 多实例环境会话无法跨实例共享
## 开启 auth.enable 后所有接口 401
- JWT 中间件需要 `Authorization: Bearer <access-token>`
- 但多数接口仍使用会话 token 校验
- 建议暂时关闭 `auth.enable` 或调整业务逻辑
## 邮件验证未生效
- `smtp.host` 为空或为 `*.example.com` 会自动关闭验证
- 检查 SMTP 配置与网络连通性
## CORS 跨域失败
- 检查 `server.allowedOrigins`
- 若未配置，服务会尝试使用 `publicUrl` 或默认本地地址
## 数据库连接失败
- `config/account.yaml` 默认端口为 5432
- Makefile 脚本默认端口为 15432
- 确保二者一致或按需调整

67
docs/usage/cli.md Normal file
View File

@ -0,0 +1,67 @@
# CLI 使用
本仓库包含多个命令行工具：
## 账号服务主程序
二进制名称由 Makefile 设置为 `xcontrol-account`，主入口在 `cmd/accountsvc`。
```bash
xcontrol-account --config config/account.yaml --log-level info
```
参数：
- `--config`：配置文件路径
- `--log-level`：`debug|info|warn|error`
## createadmin（超级管理员）
```bash
go run ./cmd/createadmin/main.go \
--driver postgres \
--dsn "$DB_URL" \
--username Admin \
--password ChangeMe \
--email admin@svc.plus
```
常用参数：
- `--driver`：`postgres` 或 `memory`
- `--dsn`：PostgreSQL DSN
- `--groups` / `--permissions`
- `--current-password`：更新已有管理员时必需
- `--mfa`：管理员启用 MFA 时必需
## migratectl（迁移 / 导出 / 导入）
```bash
# 迁移
migratectl migrate --dsn "$DB_URL"
# schema 校验
migratectl verify --dsn "$DB_URL" --schema sql/schema.sql
# 导出/导入
migratectl export --dsn "$DB_URL" --output account-export.yaml
migratectl import --dsn "$DB_URL" --file account-export.yaml
```
## syncctl（跨环境同步）
```bash
syncctl --config config/sync.yaml push
syncctl --config config/sync.yaml pull
syncctl --config config/sync.yaml mirror
```
## Makefile 快捷命令
```bash
make build
make start
make create-super-admin
make account-export
make account-import
```
相关脚本位于 `scripts/`。

148
docs/usage/config.md Normal file
View File

@ -0,0 +1,148 @@
# 配置说明
服务通过 YAML 配置文件运行，示例位于 `config/`：
- `config/account.yaml`
- `config/account-server.yaml`
- `config/account-agent.yaml`
- `config/account.cloudrun.yaml`
> `entrypoint.sh` 会根据 `CONFIG_TEMPLATE` 渲染配置到 `CONFIG_PATH`。
## 顶层字段
```yaml
mode: "server" | "agent" | "server-agent"
log:
level: info
server: {}
store: {}
session: {}
auth: {}
smtp: {}
xray: {}
agent: {}
agents: {}
```
## server
```yaml
server:
addr: ":8080"
readTimeout: 15s
writeTimeout: 15s
publicUrl: "https://accounts.svc.plus"
allowedOrigins:
- "https://console.svc.plus"
tls:
enabled: false
certFile: ""
keyFile: ""
caFile: ""
clientCAFile: ""
redirectHttp: false
```
说明：
- `allowedOrigins` 控制 CORS，若为空会回退到 `publicUrl` 或默认本地地址
- `tls.enabled` 不填时会根据 `certFile`/`keyFile` 自动判断
## store
```yaml
store:
driver: "postgres" | "memory"
dsn: "postgres://user:pass@host:5432/account?sslmode=disable"
maxOpenConns: 30
maxIdleConns: 10
```
说明：
- `memory` 适合本地快速测试
- `postgres` 需要初始化 `sql/schema.sql`
## session
```yaml
session:
ttl: 24h
```
注意：配置示例中出现的 `session.cache` / `session.redis` 字段在当前代码中未被读取。
## auth（JWT 令牌服务）
```yaml
auth:
enable: true
token:
publicToken: "..."
refreshSecret: "..."
accessSecret: "..."
accessExpiry: 1h
refreshExpiry: 168h
```
说明：启用后会为 `/api/auth/*` 的保护路由添加 JWT 中间件。
## smtp
```yaml
smtp:
host: "smtp.example.com"
port: 587
username: "apikey"
p: "s"
from: "XControl Account <no-reply@example.com>"
replyTo: ""
timeout: 10s
tls:
mode: "auto" | "starttls" | "implicit" | "none"
insecureSkipVerify: false
```
说明：
- 未配置 `host` 或使用 `*.example.com` 时，邮件验证会自动关闭
## xray
```yaml
xray:
sync:
enabled: false
interval: 5m
outputPath: "/usr/local/etc/xray/config.json"
templatePath: "account/config/xray.config.template.json"
validateCommand: []
restartCommand:
- "systemctl"
- "restart"
- "xray.service"
```
## agent
```yaml
agent:
id: "edge-node-1"
controllerUrl: "https://accounts.svc.plus"
apiToken: "replace-with-agent-token"
httpTimeout: 15s
statusInterval: 1m
syncInterval: 5m
tls:
insecureSkipVerify: false
```
## agents（Controller 侧配置）
```yaml
agents:
credentials:
- id: "account-primary"
name: "Account Server"
token: "replace-with-agent-token"
groups: ["default"]
```
该配置用于 Controller 校验 Agent 请求。

35
docs/usage/deployment.md Normal file
View File

@ -0,0 +1,35 @@
# 部署方式
## 本地或 VM
推荐通过 Makefile 与脚本执行：
```bash
make init-db
make build
make start
```
默认启动脚本 `scripts/start.sh` 使用 `config/account.yaml`。
## Docker
详见 `getting-started/installation.md`。
## Cloud Run
仓库内的 Cloud Run 配置：
- `deploy/gcp/cloud-run/service.yaml`
- `config/account.cloudrun.yaml`
特点：
- 通过 `entrypoint.sh` + `CONFIG_TEMPLATE` 注入配置
- 附带 stunnel sidecar，用于安全连接数据库
- SMTP 凭据通过 Secret 注入
## stunnel（数据库连接）
- 模板：`deploy/stunnel-account-db-client.conf` / `deploy/stunnel-account-db-server.conf`
- Cloud Run 示例：`deploy/gcp/cloud-run/stunnel.conf`
适合在数据库仅允许本地或专线访问的场景。

85
docs/usage/examples.md Normal file
View File

@ -0,0 +1,85 @@
# 常见使用场景
> 示例默认假设 `auth.enable=false`，并使用会话 token 进行认证。
## 注册（邮件验证关闭）
```bash
curl -X POST http://localhost:8080/api/auth/register \
-H 'Content-Type: application/json' \
-d '{"name":"demo","email":"demo@example.com","password":"Passw0rd!"}'
```
## 邮件验证码注册（SMTP 已启用）
```bash
# 发送验证码
curl -X POST http://localhost:8080/api/auth/register/send \
-H 'Content-Type: application/json' \
-d '{"email":"demo@example.com"}'
# 验证并完成注册
curl -X POST http://localhost:8080/api/auth/register/verify \
-H 'Content-Type: application/json' \
-d '{"email":"demo@example.com","code":"123456"}'
```
## 登录并获取会话
```bash
curl -X POST http://localhost:8080/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"identifier":"demo@example.com","password":"Passw0rd!"}'
```
返回示例（字段可能包含 `mfaToken`）：
```json
{
"message": "login successful",
"token": "<session-token>",
"expiresAt": "<timestamp>",
"user": {"id":"..."}
}
```
## 会话查询
```bash
curl -H 'Authorization: Bearer <session-token>' \
http://localhost:8080/api/auth/session
```
## MFA 绑定
```bash
# 申请 TOTP secret
curl -X POST http://localhost:8080/api/auth/mfa/totp/provision \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session-token>' \
-d '{}'
# 验证 TOTP
curl -X POST http://localhost:8080/api/auth/mfa/totp/verify \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session-token>' \
-d '{"mfaToken":"<mfa-token>","totpCode":"123456"}'
```
## 订阅 Upsert
```bash
curl -X POST http://localhost:8080/api/auth/subscriptions \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session-token>' \
-d '{"externalId":"sub_001","provider":"stripe","kind":"subscription","status":"active"}'
```
## 管理设置更新
```bash
curl -X POST http://localhost:8080/api/auth/admin/settings \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <session-token>' \
-d '{"version":1,"matrix":{"billing":{"admin":true,"operator":false}}}'
```