From ccdf676ae901931d6a9144138d91de7bfa289fcd Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Mon, 26 Jan 2026 22:21:11 +0800 Subject: [PATCH] docs: add full documentation outline --- docs/README.md | 26 +++++ docs/advanced/customization.md | 26 +++++ docs/advanced/performance.md | 24 +++++ docs/advanced/scalability.md | 17 +++ docs/advanced/security.md | 25 +++++ docs/api/auth.md | 40 +++++++ docs/api/endpoints.md | 42 ++++++++ docs/api/errors.md | 23 ++++ docs/api/overview.md | 19 ++++ docs/appendix/faq.md | 13 +++ docs/appendix/glossary.md | 10 ++ docs/appendix/references.md | 7 ++ docs/architecture/components.md | 30 ++++++ docs/architecture/design-decisions.md | 30 ++++++ docs/architecture/overview.md | 43 ++++++++ docs/architecture/roadmap.md | 11 ++ docs/development/code-structure.md | 13 +++ docs/development/contributing.md | 12 +++ docs/development/dev-setup.md | 26 +++++ docs/development/testing.md | 17 +++ docs/getting-started/concepts.md | 52 +++++++++ docs/getting-started/installation.md | 58 ++++++++++ docs/getting-started/introduction.md | 38 +++++++ docs/getting-started/quickstart.md | 69 ++++++++++++ docs/governance/license.md | 5 + docs/governance/release-process.md | 7 ++ docs/governance/security-policy.md | 7 ++ docs/integrations/ai-providers.md | 8 ++ docs/integrations/cloud.md | 24 +++++ docs/integrations/databases.md | 29 +++++ docs/operations/backup.md | 17 +++ docs/operations/logging.md | 10 ++ docs/operations/monitoring.md | 9 ++ docs/operations/troubleshooting.md | 28 +++++ docs/usage/cli.md | 67 ++++++++++++ docs/usage/config.md | 148 ++++++++++++++++++++++++++ docs/usage/deployment.md | 35 ++++++ docs/usage/examples.md | 85 +++++++++++++++ 38 files changed, 1150 insertions(+) create mode 100644 docs/README.md create mode 100644 docs/advanced/customization.md create mode 100644 docs/advanced/performance.md create mode 100644 docs/advanced/scalability.md create mode 100644 docs/advanced/security.md create mode 100644 docs/api/auth.md create mode 100644 docs/api/endpoints.md create mode 100644 docs/api/errors.md create mode 100644 docs/api/overview.md create mode 100644 docs/appendix/faq.md create mode 100644 docs/appendix/glossary.md create mode 100644 docs/appendix/references.md create mode 100644 docs/architecture/components.md create mode 100644 docs/architecture/design-decisions.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/architecture/roadmap.md create mode 100644 docs/development/code-structure.md create mode 100644 docs/development/contributing.md create mode 100644 docs/development/dev-setup.md create mode 100644 docs/development/testing.md create mode 100644 docs/getting-started/concepts.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/introduction.md create mode 100644 docs/getting-started/quickstart.md create mode 100644 docs/governance/license.md create mode 100644 docs/governance/release-process.md create mode 100644 docs/governance/security-policy.md create mode 100644 docs/integrations/ai-providers.md create mode 100644 docs/integrations/cloud.md create mode 100644 docs/integrations/databases.md create mode 100644 docs/operations/backup.md create mode 100644 docs/operations/logging.md create mode 100644 docs/operations/monitoring.md create mode 100644 docs/operations/troubleshooting.md create mode 100644 docs/usage/cli.md create mode 100644 docs/usage/config.md create mode 100644 docs/usage/deployment.md create mode 100644 docs/usage/examples.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..842c4fa --- /dev/null +++ b/docs/README.md @@ -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` 中有交叉引用。 diff --git a/docs/advanced/customization.md b/docs/advanced/customization.md new file mode 100644 index 0000000..84d663d --- /dev/null +++ b/docs/advanced/customization.md @@ -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` +- 建议保持统一错误结构 diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md new file mode 100644 index 0000000..b94977a --- /dev/null +++ b/docs/advanced/performance.md @@ -0,0 +1,24 @@ +# 性能与扩展性 + +## 数据库连接池 + +配置项： +- `store.maxOpenConns` +- `store.maxIdleConns` + +合理设置以避免数据库过载或连接不足。 + +## 会话存储 + +- 当前会话保存在进程内存 +- 高并发或多实例场景建议外部化（未来可扩展） + +## Xray 同步 + +- `xray.sync.interval` 控制同步频率 +- 同步过于频繁会增加 I/O 与重启开销 + +## 日志级别 + +- `log.level` 支持 `debug|info|warn|error` +- 生产环境建议使用 `info` 或 `warn` diff --git a/docs/advanced/scalability.md b/docs/advanced/scalability.md new file mode 100644 index 0000000..ca45fcd --- /dev/null +++ b/docs/advanced/scalability.md @@ -0,0 +1,17 @@ +# 高可用与水平扩展 + +## 当前限制 + +- 会话存储在内存中，无法在多实例间共享 +- 多实例部署会导致用户在不同实例间会话失效 + +## 建议方向 + +- 引入集中式会话存储（如 Redis） +- API 层保持无状态，通过负载均衡扩展 +- 数据库采用主从或 pglogical 多主架构 + +## Agent 扩展 + +- Controller 通过配置 `agents.credentials` 支持多 Agent +- Agent 状态通过内存 Registry 维护 diff --git a/docs/advanced/security.md b/docs/advanced/security.md new file mode 100644 index 0000000..14c8094 --- /dev/null +++ b/docs/advanced/security.md @@ -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` diff --git a/docs/api/auth.md b/docs/api/auth.md new file mode 100644 index 0000000..6deac7b --- /dev/null +++ b/docs/api/auth.md @@ -0,0 +1,40 @@ +# 认证与鉴权 + +## 会话认证（默认） + +1) 登录 `POST /api/auth/login` 成功后返回： +- `token`：会话 token +- `expiresAt` +- `user` + +2) 客户端后续请求携带： +- `Authorization: Bearer ` 或 +- Cookie `xc_session=` + +## 邮件验证 + +- 发送验证码：`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 `，但业务逻辑仍可能需要会话 token + +建议：若主要使用会话认证，请将 `auth.enable` 设为 `false`。 diff --git a/docs/api/endpoints.md b/docs/api/endpoints.md new file mode 100644 index 0000000..02fde5a --- /dev/null +++ b/docs/api/endpoints.md @@ -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 `。 diff --git a/docs/api/errors.md b/docs/api/errors.md new file mode 100644 index 0000000..e9d6b80 --- /dev/null +++ b/docs/api/errors.md @@ -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/` 中查阅。 diff --git a/docs/api/overview.md b/docs/api/overview.md new file mode 100644 index 0000000..281a051 --- /dev/null +++ b/docs/api/overview.md @@ -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 ` 或 `xc_session` Cookie +- JWT（可选）：启用 `auth.enable` 后，对 `/api/auth/*` 保护路由增加 JWT 校验 + +> 注意：当前实现中，大部分保护路由仍依赖会话 token。若开启 JWT 中间件，需确保请求同时满足会话逻辑（详见 `api/auth.md` 的说明）。 diff --git a/docs/appendix/faq.md b/docs/appendix/faq.md new file mode 100644 index 0000000..e8e7823 --- /dev/null +++ b/docs/appendix/faq.md @@ -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`。 diff --git a/docs/appendix/glossary.md b/docs/appendix/glossary.md new file mode 100644 index 0000000..94b18a9 --- /dev/null +++ b/docs/appendix/glossary.md @@ -0,0 +1,10 @@ +# 术语表 + +- Account Service：账号服务主程序 +- Session：登录会话 token +- MFA：多因素认证（TOTP） +- Agent：部署在边缘节点的同步程序 +- Controller：管理 Agent 的中心账号服务 +- Xray：代理配置同步目标 +- pgsync：逻辑导出/导入同步工具 +- pglogical：PostgreSQL 逻辑复制扩展 diff --git a/docs/appendix/references.md b/docs/appendix/references.md new file mode 100644 index 0000000..f2e2553 --- /dev/null +++ b/docs/appendix/references.md @@ -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` diff --git a/docs/architecture/components.md b/docs/architecture/components.md new file mode 100644 index 0000000..57ab90f --- /dev/null +++ b/docs/architecture/components.md @@ -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`：管理员权限矩阵与用户指标聚合 diff --git a/docs/architecture/design-decisions.md b/docs/architecture/design-decisions.md new file mode 100644 index 0000000..93b8251 --- /dev/null +++ b/docs/architecture/design-decisions.md @@ -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`） diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..5a95482 --- /dev/null +++ b/docs/architecture/overview.md @@ -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 为可选能力，需与会话机制配合使用 diff --git a/docs/architecture/roadmap.md b/docs/architecture/roadmap.md new file mode 100644 index 0000000..c31111e --- /dev/null +++ b/docs/architecture/roadmap.md @@ -0,0 +1,11 @@ +# Roadmap（可选） + +以下为基于现状的可能演进方向，具体以实际需求为准： + +- 会话外部化：引入 Redis 等持久化会话存储 +- 认证统一：会话与 JWT 令牌机制整合 +- API 描述：补充 OpenAPI/Swagger +- 监控指标：新增 Prometheus / OpenTelemetry 输出 +- 插件化：订阅与支付渠道适配层 + +> 说明：以上方向尚未在当前代码中实现，仅供规划参考。 diff --git a/docs/development/code-structure.md b/docs/development/code-structure.md new file mode 100644 index 0000000..17d7920 --- /dev/null +++ b/docs/development/code-structure.md @@ -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/`：构建与运维脚本 diff --git a/docs/development/contributing.md b/docs/development/contributing.md new file mode 100644 index 0000000..a4b8028 --- /dev/null +++ b/docs/development/contributing.md @@ -0,0 +1,12 @@ +# 贡献指南 + +欢迎贡献本项目。建议流程： + +1. 阅读 `docs/development/dev-setup.md` +2. 创建分支并保持提交粒度清晰 +3. 运行 `go test ./...` +4. 确保文档与配置同步更新 + +如需调整数据库结构，请同步更新： +- `sql/schema.sql` +- 相关迁移与测试 diff --git a/docs/development/dev-setup.md b/docs/development/dev-setup.md new file mode 100644 index 0000000..0d83d03 --- /dev/null +++ b/docs/development/dev-setup.md @@ -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`，未安装会提示安装链接。 diff --git a/docs/development/testing.md b/docs/development/testing.md new file mode 100644 index 0000000..3a184cd --- /dev/null +++ b/docs/development/testing.md @@ -0,0 +1,17 @@ +# 测试策略 + +## 单元测试 + +```bash +make test +# 或 +go test ./... +``` + +## 集成测试 + +```bash +make integration-test +``` + +集成测试会执行初始化与创建管理员流程，依赖本地数据库环境。 diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md new file mode 100644 index 0000000..bfde2d9 --- /dev/null +++ b/docs/getting-started/concepts.md @@ -0,0 +1,52 @@ +# 核心概念 + +以下概念来自当前代码与数据库结构，帮助理解账户服务的核心模型。 + +## 用户（User） + +用户包含： +- `username` / `email` / `password` +- `role` 与 `level`：`admin` / `operator` / `user` +- `groups` / `permissions` +- MFA 状态（TOTP）与邮箱验证状态 + +## 会话（Session） + +- 登录成功后产生会话 token +- 会话默认保存在进程内存（非持久化） +- 客户端可使用 `xc_session` Cookie 或 `Authorization: Bearer ` + +## 邮件验证 + +- 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 同步脚本 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..8bee115 --- /dev/null +++ b/docs/getting-started/installation.md @@ -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 环境变量注入示例 diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md new file mode 100644 index 0000000..8ccf0e9 --- /dev/null +++ b/docs/getting-started/introduction.md @@ -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` 完成最小启动示例。 diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md new file mode 100644 index 0000000..b906160 --- /dev/null +++ b/docs/getting-started/quickstart.md @@ -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 ' http://localhost:8080/api/auth/session +``` + +> 注意：会话保存在进程内存，重启服务会使会话失效。 diff --git a/docs/governance/license.md b/docs/governance/license.md new file mode 100644 index 0000000..85dfe64 --- /dev/null +++ b/docs/governance/license.md @@ -0,0 +1,5 @@ +# License + +当前仓库未包含许可证文件（未检测到 `LICENSE`）。 + +如需开放或限制使用权限，请补充项目许可证并在此说明。 diff --git a/docs/governance/release-process.md b/docs/governance/release-process.md new file mode 100644 index 0000000..990a570 --- /dev/null +++ b/docs/governance/release-process.md @@ -0,0 +1,7 @@ +# 发布流程 + +当前仓库未定义正式发布流程。可以考虑： + +- 使用 Git tag 标记版本 +- 记录变更日志（CHANGELOG） +- 为生产部署准备固定镜像标签 diff --git a/docs/governance/security-policy.md b/docs/governance/security-policy.md new file mode 100644 index 0000000..858055a --- /dev/null +++ b/docs/governance/security-policy.md @@ -0,0 +1,7 @@ +# 安全策略 + +当前仓库未定义正式的安全漏洞报告流程。 + +建议补充： +- 安全邮箱或工单入口 +- 处理时限与披露策略 diff --git a/docs/integrations/ai-providers.md b/docs/integrations/ai-providers.md new file mode 100644 index 0000000..bd92dd1 --- /dev/null +++ b/docs/integrations/ai-providers.md @@ -0,0 +1,8 @@ +# AI Providers + +当前账号服务未集成任何 AI 模型或推理服务。 + +若未来需要对接 OpenAI / NVIDIA / OSS 模型，可在此文档补充： +- 鉴权方式 +- 请求限流 +- 费用与配额管理 diff --git a/docs/integrations/cloud.md b/docs/integrations/cloud.md new file mode 100644 index 0000000..180fd9e --- /dev/null +++ b/docs/integrations/cloud.md @@ -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 配置即可。 diff --git a/docs/integrations/databases.md b/docs/integrations/databases.md new file mode 100644 index 0000000..8f888fa --- /dev/null +++ b/docs/integrations/databases.md @@ -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 +``` diff --git a/docs/operations/backup.md b/docs/operations/backup.md new file mode 100644 index 0000000..1a150a8 --- /dev/null +++ b/docs/operations/backup.md @@ -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 +``` diff --git a/docs/operations/logging.md b/docs/operations/logging.md new file mode 100644 index 0000000..87a975d --- /dev/null +++ b/docs/operations/logging.md @@ -0,0 +1,10 @@ +# 日志 + +- 日志使用 `slog` 文本格式输出到 stdout +- 级别通过 `log.level` 控制（debug/info/warn/error） + +示例： +```yaml +log: + level: info +``` diff --git a/docs/operations/monitoring.md b/docs/operations/monitoring.md new file mode 100644 index 0000000..1ad4f4d --- /dev/null +++ b/docs/operations/monitoring.md @@ -0,0 +1,9 @@ +# 监控 + +当前服务提供以下监控入口： + +- `GET /healthz`：存活检查 +- `GET /api/auth/admin/users/metrics`：用户指标（需管理员） +- 日志输出：stdout + +暂未提供 Prometheus/OpenTelemetry 指标，需要时可在此扩展。 diff --git a/docs/operations/troubleshooting.md b/docs/operations/troubleshooting.md new file mode 100644 index 0000000..75918ae --- /dev/null +++ b/docs/operations/troubleshooting.md @@ -0,0 +1,28 @@ +# 常见问题排查 + +## 登录成功后提示 session invalid + +- 会话存储在内存中，重启服务会导致失效 +- 多实例环境会话无法跨实例共享 + +## 开启 auth.enable 后所有接口 401 + +- JWT 中间件需要 `Authorization: Bearer ` +- 但多数接口仍使用会话 token 校验 +- 建议暂时关闭 `auth.enable` 或调整业务逻辑 + +## 邮件验证未生效 + +- `smtp.host` 为空或为 `*.example.com` 会自动关闭验证 +- 检查 SMTP 配置与网络连通性 + +## CORS 跨域失败 + +- 检查 `server.allowedOrigins` +- 若未配置，服务会尝试使用 `publicUrl` 或默认本地地址 + +## 数据库连接失败 + +- `config/account.yaml` 默认端口为 5432 +- Makefile 脚本默认端口为 15432 +- 确保二者一致或按需调整 diff --git a/docs/usage/cli.md b/docs/usage/cli.md new file mode 100644 index 0000000..d42fbf5 --- /dev/null +++ b/docs/usage/cli.md @@ -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/`。 diff --git a/docs/usage/config.md b/docs/usage/config.md new file mode 100644 index 0000000..766a923 --- /dev/null +++ b/docs/usage/config.md @@ -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 " + 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 请求。 diff --git a/docs/usage/deployment.md b/docs/usage/deployment.md new file mode 100644 index 0000000..a9b6213 --- /dev/null +++ b/docs/usage/deployment.md @@ -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` + +适合在数据库仅允许本地或专线访问的场景。 diff --git a/docs/usage/examples.md b/docs/usage/examples.md new file mode 100644 index 0000000..187b366 --- /dev/null +++ b/docs/usage/examples.md @@ -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": "", + "expiresAt": "", + "user": {"id":"..."} +} +``` + +## 会话查询 + +```bash +curl -H 'Authorization: Bearer ' \ + 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 ' \ + -d '{}' + +# 验证 TOTP +curl -X POST http://localhost:8080/api/auth/mfa/totp/verify \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -d '{"mfaToken":"","totpCode":"123456"}' +``` + +## 订阅 Upsert + +```bash +curl -X POST http://localhost:8080/api/auth/subscriptions \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer ' \ + -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 ' \ + -d '{"version":1,"matrix":{"billing":{"admin":true,"operator":false}}}' +```