From 3ee4a55d3deee0718d1dd45e48a28f2bdb2d3537 Mon Sep 17 00:00:00 2001
From: shenlan <manbuzhe2009@qq.com>
Date: Tue, 30 Sep 2025 19:33:42 +0800
Subject: [PATCH] docs: add account service guidance (#324)

---
 docs/account-service-configuration.md | 124 ++++++++++++++++++++++++++
 docs/account-service-deployment.md    |  90 +++++++++++++++++++
 docs/account-service-design.md        |  82 +++++++++++++++++
 3 files changed, 296 insertions(+)
 create mode 100644 docs/account-service-configuration.md
 create mode 100644 docs/account-service-deployment.md
 create mode 100644 docs/account-service-design.md

diff --git a/docs/account-service-configuration.md b/docs/account-service-configuration.md
new file mode 100644
index 0000000..8043d0a
--- /dev/null
+++ b/docs/account-service-configuration.md
@@ -0,0 +1,124 @@
+# Account Service 配置指南
+
+本文档说明账号服务可用的配置项、加载顺序以及示例，方便在不同环境中快速调整运行参数。
+
+## 1. 配置加载策略
+
+当前服务入口（`account/cmd/accountsvc/main.go`）直接创建 Gin 引擎并注册路由，尚未接入统一的配置加载逻辑。【F:account/cmd/accountsvc/main.go†L1-L12】
+
+为满足生产需求，建议按以下优先级加载配置：
+
+1. **命令行参数**：覆盖性最高，用于临时指定端口或配置文件路径。
+2. **环境变量**：适用于容器化部署，通过 `ACCOUNT_*` 前缀管理。
+3. **配置文件**：默认从 `config/account.yaml` 或 `config/account.json` 中读取。
+4. **内置默认值**：在 `account/config/config.go` 中定义结构体并赋予默认值，保证在缺省配置下仍可运行。【F:account/config/config.go†L1-L5】
+
+## 2. 建议的配置结构
+
+未来扩展时，可按以下结构扩充 `Config`：
+
+```yaml
+server:
+  addr: ":8080"
+  readTimeout: 10s
+  writeTimeout: 10s
+  idleTimeout: 60s
+
+store:
+  driver: "memory"   # 可选：memory、postgres、mysql
+  dsn: "postgres://user:pass@host:5432/account?sslmode=disable"
+  maxOpenConns: 20
+  maxIdleConns: 5
+  connMaxLifetime: 30m
+
+session:
+  ttl: 24h
+  cache: "memory"   # 可选：memory、redis
+  redis:
+    addr: "redis:6379"
+    password: ""
+    db: 0
+
+authProviders:
+  - name: "oidc"
+    issuer: "https://idp.example.com"
+    clientID: "xcontrol"
+    clientSecret: "${OIDC_CLIENT_SECRET}"
+  - name: "ldap"
+    addr: "ldap://ldap.example.com:389"
+    baseDN: "dc=example,dc=com"
+    bindDN: "cn=admin,dc=example,dc=com"
+    bindPassword: "${LDAP_BIND_PASSWORD}"
+```
+
+## 3. 环境变量示例
+
+| 变量名 | 说明 | 示例 |
+| ------ | ---- | ---- |
+| `ACCOUNT_SERVER_ADDR` | 服务监听地址 | `:8080` |
+| `ACCOUNT_STORE_DRIVER` | 存储驱动类型 | `postgres` |
+| `ACCOUNT_STORE_DSN` | 存储连接串 | `postgres://user:pass@db:5432/account` |
+| `ACCOUNT_SESSION_TTL` | 会话有效期（秒或 Go duration） | `24h` |
+| `ACCOUNT_REDIS_ADDR` | Redis 地址（当 cache=redis 时使用） | `redis:6379` |
+| `ACCOUNT_LOG_LEVEL` | 日志级别 | `info` |
+
+在容器或 CI/CD 中，可借助 Secret/ConfigMap 注入敏感值，避免直接写入镜像。
+
+## 4. 配置示例
+
+### 4.1 开发环境
+
+```yaml
+server:
+  addr: ":8080"
+
+store:
+  driver: "memory"
+
+session:
+  ttl: 24h
+  cache: "memory"
+```
+
+### 4.2 测试/预生产环境
+
+```yaml
+server:
+  addr: ":8080"
+  readTimeout: 15s
+  writeTimeout: 15s
+
+store:
+  driver: "postgres"
+  dsn: "postgres://acct:acctpass@postgres:5432/account?sslmode=disable"
+  maxOpenConns: 30
+  maxIdleConns: 10
+
+session:
+  ttl: 24h
+  cache: "redis"
+  redis:
+    addr: "redis:6379"
+    password: "${REDIS_PASSWORD}"
+
+authProviders:
+  - name: "oidc"
+    issuer: "https://idp-pre.example.com"
+    clientID: "xcontrol"
+    clientSecret: "${OIDC_SECRET}"
+```
+
+## 5. 配置校验与回滚
+
+- 在服务启动时验证必需字段是否填写，例如当 `driver=postgres` 时必须提供 `dsn`。
+- 提供配置热加载或版本化策略，例如通过 GitOps 将配置存储于仓库，变更可回滚。
+- 通过单元测试验证不同配置组合的解析结果，确保新字段向下兼容。
+
+## 6. 与代码协同
+
+- 在 `account/api` 中读取 `session.ttl` 替换硬编码的 `24 * time.Hour`，实现配置化。【F:account/api/api.go†L18-L171】
+- 在 `account/internal/store` 中根据 `store.driver` 实例化不同实现，实现从内存到数据库的无缝切换。【F:account/internal/store/store.go†L31-L109】
+- 在 `account/internal/auth` 中根据 `authProviders` 列表注册外部认证方式，实现多身份源并行校验。【F:account/internal/auth/auth.go†L1-L6】
+
+---
+随着服务演进，应持续完善 `Config` 结构与加载逻辑，并在此文档中同步更新字段说明。
diff --git a/docs/account-service-deployment.md b/docs/account-service-deployment.md
new file mode 100644
index 0000000..4c36ec7
--- /dev/null
+++ b/docs/account-service-deployment.md
@@ -0,0 +1,90 @@
+# Account Service 部署指南
+
+本文档介绍如何在不同环境中部署 XControl 账号服务，包括本地开发、容器化以及生产环境的关键注意事项。
+
+## 1. 运行时依赖
+
+- Go 1.22 及以上版本，用于编译服务。
+- （可选）PostgreSQL、Redis 等外部组件，当前实现默认使用内存存储，可在后续扩展中替换。
+- Make 与 Git（可选），用于辅助构建与版本管理。
+
+## 2. 本地开发部署
+
+1. **拉取代码**
+   ```bash
+   git clone <repo-url>
+   cd XControl
+   ```
+
+2. **启动服务**
+   ```bash
+   go run ./account/cmd/accountsvc
+   ```
+   默认监听 `:8080`，可通过 `curl http://127.0.0.1:8080/healthz` 检查服务状态。
+
+3. **交互测试**
+   - 注册账号：
+     ```bash
+     curl -X POST http://127.0.0.1:8080/v1/register \
+       -H 'Content-Type: application/json' \
+       -d '{"name":"demo","email":"demo@example.com","password":"Secret123"}'
+     ```
+   - 登录获取 token：
+     ```bash
+     curl -X POST http://127.0.0.1:8080/v1/login \
+       -H 'Content-Type: application/json' \
+       -d '{"email":"demo@example.com","password":"Secret123"}'
+     ```
+
+## 3. Docker 镜像部署
+
+1. **构建镜像（示例 Dockerfile 需后续补充）**
+   ```bash
+   docker build -t xcontrol/account-service -f deploy/account/Dockerfile .
+   ```
+
+2. **运行容器**
+   ```bash
+   docker run -d \
+     --name account-service \
+     -p 8080:8080 \
+     xcontrol/account-service
+   ```
+
+3. **查看日志**
+   ```bash
+   docker logs -f account-service
+   ```
+
+若需与 PostgreSQL、Redis 集成，可通过环境变量或配置文件挂载方式将连接信息传入容器。
+
+## 4. Kubernetes/Helm 部署（建议）
+
+- 在 `deploy/account` 目录中维护 Helm Chart 或 Kustomize 模板，定义 Service、Deployment、ConfigMap 等资源。
+- 关键参数：
+  - 副本数 `replicaCount`，生产环境建议至少 2 个副本以实现高可用。
+  - 探针：配置 `livenessProbe` 与 `readinessProbe` 指向 `/healthz`。
+  - 资源限制：根据用户规模设置 CPU/内存请求与限制。
+  - Secret 管理：通过 Kubernetes Secret 注入数据库、缓存或第三方身份源的凭据。
+
+## 5. 灰度与回滚策略
+
+- 采用 RollingUpdate 策略滚动发布，确保新旧副本并行运行。
+- 配置 `maxUnavailable=0`、`maxSurge=1`（或按需调整），避免服务中断。
+- 通过标记镜像版本或 Git Commit Hash 追踪上线版本，出问题时可快速回滚至上一版本。
+
+## 6. 监控与日志
+
+- 日志：默认输出到标准输出，可挂载至日志采集系统（如 Loki、ELK）。
+- 指标：后续可集成 Prometheus 指标暴露，便于观察登录成功率、请求延迟、会话数量等关键指标。
+- 告警：基于探针失败、登录失败率飙升、token 生成错误等指标配置告警。
+
+## 7. 安全加固建议
+
+- 在容器或集群层启用网络策略，仅开放必要端口。
+- 配置 HTTPS/TLS 网关，保证传输安全。
+- 对外部依赖（数据库、缓存）使用专用账号与最小权限策略。
+- 部署前进行漏洞扫描与依赖安全检查。
+
+---
+以上步骤仅覆盖核心流程，实际生产部署需根据企业环境补充网络、合规等细节。
diff --git a/docs/account-service-design.md b/docs/account-service-design.md
new file mode 100644
index 0000000..65e9b2f
--- /dev/null
+++ b/docs/account-service-design.md
@@ -0,0 +1,82 @@
+# Account Service 设计说明
+
+本文档描述 `account` 目录下账号服务的现状与演进方向，帮助研发、测试与运维人员快速理解该组件的职责、核心流程与可扩展性。
+
+## 1. 背景与目标
+
+账号服务用于在 XControl 生态内提供统一的注册、登录与会话查询能力，为后续的权限管控、业务系统集成提供基础身份数据。
+
+主要目标：
+
+- 提供面向用户的注册与登录接口，支持以邮箱为主键的账号体系。
+- 提供标准的健康检查与会话管理接口，便于其它服务探活与拉取当前登录用户信息。
+- 提供可替换的存储与认证接口，满足从 PoC 到生产的不同部署需求。
+
+## 2. 系统架构
+
+账号服务采用 Go 语言实现，入口位于 `account/cmd/accountsvc/main.go`，默认使用 Gin 框架启动 HTTP 服务并注册 REST API 路由。【F:account/cmd/accountsvc/main.go†L1-L12】
+
+核心模块划分如下：
+
+- `account/api`: 定义 REST API，并实现用户注册、登录、会话维护等业务逻辑。【F:account/api/api.go†L1-L190】
+- `account/internal/store`: 提供用户数据的读写接口与内存实现，后续可扩展至数据库存储。【F:account/internal/store/store.go†L1-L109】
+- `account/internal/auth`: 声明可插拔的第三方认证提供方接口，为接入 LDAP/OIDC 等外部系统提供抽象。【F:account/internal/auth/auth.go†L1-L6】
+- `account/internal/cache`: 预留会话缓存接口，便于集成 Redis 等缓存组件。【F:account/internal/cache/cache.go†L1-L6】
+- `account/config`: 管理服务配置结构体（当前为空定义，未来将扩展字段）。【F:account/config/config.go†L1-L5】
+
+内部调用关系示意：
+
+```
+Gin Router → API Handler → Store / Session Manager → 数据存储
+                               ↘ Auth Provider (可选)
+```
+
+## 3. 接口设计
+
+### 3.1 健康检查
+- `GET /healthz`
+- 返回 `{ "status": "ok" }`，供探活或依赖服务检测。
+
+### 3.2 用户注册
+- `POST /v1/register`
+- 请求体：`{ "name": string, "email": string, "password": string }`
+- 功能：创建新用户，内部对密码执行 `bcrypt` 哈希后写入存储，返回脱敏后的用户信息。
+
+### 3.3 用户登录
+- `POST /v1/login`
+- 请求体：`{ "email": string, "password": string }`
+- 功能：校验凭据，通过内存存储读取用户并验证哈希密码，成功后生成 24 小时有效的会话 token。【F:account/api/api.go†L65-L136】
+
+### 3.4 查询会话
+- `GET /v1/session`
+- Header 中提供 `Authorization: Bearer <token>` 或查询参数 `token`。
+- 功能：校验 token，返回关联用户信息。【F:account/api/api.go†L138-L176】
+
+### 3.5 注销会话
+- `DELETE /v1/session`
+- Header 或查询参数传入 token，删除内存中的会话记录。【F:account/api/api.go†L178-L190】
+
+## 4. 数据模型
+
+当前实现使用内存存储，结构体 `store.User` 定义了最小必要字段：`ID`、`Name`、`Email`、`PasswordHash` 与 `CreatedAt` 时间戳。【F:account/internal/store/store.go†L12-L18】
+
+`memoryStore` 负责提供线程安全的增删查能力，并在创建用户时自动生成 UUID 与 UTC 时间，保证多实例场景中的唯一性。未来替换为数据库时，可在 `Store` 接口的基础上新增实现即可。【F:account/internal/store/store.go†L31-L109】
+
+## 5. 安全与扩展
+
+- **密码存储**：使用 `bcrypt` 哈希，防止明文泄露。【F:account/api/api.go†L90-L108】
+- **会话管理**：会话 token 为 32 字节随机数生成的十六进制字符串，并设置 24 小时过期，过期后自动清理。【F:account/api/api.go†L112-L171】
+- **扩展点**：
+  - 可在 `Store` 接口层新增 PostgreSQL、MySQL 等实现。
+  - 可实现 `auth.Provider` 接口以支持外部身份源认证，再与内部用户绑定。
+  - 可基于 `cache.Cache` 抽象接入 Redis，实现跨实例的会话共享。
+
+## 6. 后续计划
+
+1. 丰富 `config.Config` 字段，支持从 YAML/ENV 读取监听端口、数据库、缓存等配置。
+2. 将内存会话迁移到可持久化/分布式缓存，支持水平扩展。
+3. 引入审计日志、登录失败限制等安全机制。
+4. 整合统一的错误码与 API 文档输出，便于前后端协同。
+
+---
+本文档需根据功能演进持续维护，以确保服务的设计意图与实现保持一致。