214 lines
6.0 KiB
Markdown
214 lines
6.0 KiB
Markdown
# User Management System (UMS)
|
||
|
||
企业级用户管理系统，支持 RBAC 角色权限管理、多因素认证、设备信任和安全审计。
|
||
|
||
## 快速开始
|
||
|
||
### 安装 UMS CLI
|
||
|
||
```bash
|
||
# 下载对应平台的二进制文件
|
||
# Linux/macOS
|
||
curl -L -o ums https://github.com/user-management-system/ums/releases/latest/download/ums-linux-amd64
|
||
chmod +x ums
|
||
|
||
# Windows
|
||
curl -L -o ums.exe https://github.com/user-management-system/ums/releases/latest/download/ums-windows-amd64.exe
|
||
|
||
# 或使用 Go 安装
|
||
go install github.com/user-management-system/cmd/ums@latest
|
||
```
|
||
|
||
### 初始化系统
|
||
|
||
```bash
|
||
# 交互式初始化（推荐）
|
||
ums init
|
||
|
||
# 非交互式初始化
|
||
ums init \
|
||
--admin-user admin \
|
||
--admin-pass MySecretPassword123 \
|
||
--admin-email admin@example.com \
|
||
--cors-origin http://localhost:3000
|
||
```
|
||
|
||
初始化命令会：
|
||
1. 生成安全的 JWT 密钥
|
||
2. 创建配置文件 `config.yaml` 和 `.env`
|
||
3. 创建数据库目录并执行迁移
|
||
4. 初始化默认角色、权限和管理员账号
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
ums serve
|
||
```
|
||
|
||
服务启动后访问 `http://localhost:8080/health` 确认服务正常运行。
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd frontend/admin
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── cmd/
|
||
│ ├── ums/ # UMS CLI 入口
|
||
│ │ └── cmd/ # CLI 子命令
|
||
│ │ ├── init.go # 初始化命令
|
||
│ │ ├── serve.go # 服务启动命令
|
||
│ │ └── version.go # 版本命令
|
||
│ └── server/ # 后端服务入口
|
||
├── internal/ # 后端代码
|
||
│ ├── api/handler/ # HTTP 处理器
|
||
│ ├── api/middleware/ # 中间件（认证、权限、限流）
|
||
│ ├── auth/ # 认证服务（JWT/SSO）
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── service/ # 业务逻辑层
|
||
│ ├── server/ # 服务器核心逻辑
|
||
│ └── domain/ # 领域模型
|
||
├── frontend/admin/ # 管理后台前端
|
||
├── configs/ # 配置文件
|
||
├── docs/ # 详细文档
|
||
└── data/ # SQLite 数据库目录
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 用户管理 | 注册、登录、CRUD、批量操作 |
|
||
| RBAC | 角色继承、权限细粒度控制 |
|
||
| TOTP | Google Authenticator 二次验证 |
|
||
| 设备信任 | 信任设备免二次验证 |
|
||
| 登录日志 | 完整操作审计 |
|
||
| Webhook | 事件通知（user.created/deleted 等）|
|
||
| SSO | CAS 协议支持 |
|
||
|
||
## 安全特性
|
||
|
||
| 安全修复 | 状态 |
|
||
|----------|------|
|
||
| LIKE 查询 SQL 注入防护 | ✅ 已修复 |
|
||
| 登录失败计数器原子操作 | ✅ 已修复 |
|
||
| Refresh Token 黑名单 fail-closed | ✅ 已修复 |
|
||
| 验证码 Replay 防护 | ✅ 已修复 |
|
||
| CORS 危险配置检测 | ✅ 已修复 |
|
||
| UpdateUser IDOR 授权检查 | ✅ 已修复 |
|
||
| Login TOTP 设备信任门禁 | ✅ 已修复 |
|
||
| 游标分页排序一致性 | ✅ 已修复 |
|
||
| 错误信息泄露防护 | ✅ 已修复 |
|
||
| OAuth context 正确传播 | ✅ 已修复 |
|
||
| 密码修改后 Token 失效（PCE） | ✅ 已修复 |
|
||
|
||
## CLI 命令
|
||
|
||
```bash
|
||
ums init # 初始化系统（交互式或非交互式）
|
||
ums serve # 启动服务器
|
||
ums version # 显示版本信息
|
||
|
||
# ums serve 选项
|
||
ums serve --port 8080 # 指定端口
|
||
ums serve --config ./prod.yaml # 指定配置文件
|
||
|
||
# ums init 选项
|
||
ums init --db-type sqlite # 数据库类型
|
||
ums init --db-path ./data/ums.db # 数据库路径
|
||
ums init --redis-enable # 启用 Redis
|
||
ums init --redis-host localhost # Redis 地址
|
||
ums init --admin-user admin # 管理员用户名
|
||
ums init --admin-pass MyPassword123 # 管理员密码
|
||
ums init --admin-email admin@example.com # 管理员邮箱
|
||
ums init --port 8080 # 服务端口
|
||
ums init --cors-origin http://example.com # CORS 域名
|
||
ums init --yes # 跳过确认
|
||
```
|
||
|
||
## 配置文件
|
||
|
||
初始化后生成以下配置文件：
|
||
|
||
**config.yaml** - 主配置文件
|
||
```yaml
|
||
server:
|
||
port: 8080
|
||
mode: release
|
||
database:
|
||
type: sqlite
|
||
dbname: "./data/user_management.db"
|
||
jwt:
|
||
secret: "<自动生成的密钥>"
|
||
redis:
|
||
enabled: false
|
||
```
|
||
|
||
**.env** - 环境变量（包含敏感信息，请勿提交）
|
||
```bash
|
||
JWT_SECRET=<自动生成的密钥>
|
||
BOOTSTRAP_SECRET=<自动生成的密钥>
|
||
DEFAULT_ADMIN_EMAIL=admin@example.com
|
||
DEFAULT_ADMIN_PASSWORD=<您设置的密码>
|
||
```
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 构建 CLI
|
||
make build-cli
|
||
|
||
# 构建所有平台 CLI
|
||
make build-cli-all
|
||
|
||
# 构建服务器
|
||
go build ./cmd/server
|
||
|
||
# 后端最低验证矩阵
|
||
go vet ./...
|
||
go test ./... -count=1
|
||
|
||
# 前端最低验证矩阵（显式移除 NODE_ENV=production 干扰）
|
||
cd frontend/admin && env -u NODE_ENV npm run lint
|
||
cd frontend/admin && env -u NODE_ENV npm run build
|
||
cd frontend/admin && env -u NODE_ENV npm run test:run
|
||
```
|
||
|
||
## 部署
|
||
|
||
- 开发部署：`docs/DEPLOYMENT.md`
|
||
- 生产部署：`DEPLOY_GUIDE.md`
|
||
- 运行手册：`docs/guides/` 目录下的 7 个 Runbook
|
||
|
||
## 测试状态（2026-05-28 live snapshot）
|
||
|
||
| 测试类型 | 状态 |
|
||
|----------|------|
|
||
| Go 构建 | ✅ 通过 |
|
||
| Go vet | ✅ 通过 |
|
||
| Go 测试 | ✅ 通过（`go test ./... -count=1`） |
|
||
| 前端 lint | ✅ 通过 |
|
||
| 前端构建 | ✅ 通过 |
|
||
| 前端测试 | ✅ 通过（82 files / 522 tests） |
|
||
| 依赖审计 | ✅ 通过（prod/dev 均 0 漏洞） |
|
||
| 浏览器级 E2E | ✅ 通过（Playwright CDP full-chain） |
|
||
|
||
## 项目状态
|
||
|
||
完整项目状态：`docs/status/REAL_PROJECT_STATUS.md`
|
||
|
||
**2026-05-28 最新状态：**
|
||
- 后端 build / vet / full test matrix 全绿
|
||
- 前端 lint / build / unit test 全绿
|
||
- 前端 dev toolchain 审计收敛为 0 漏洞
|
||
- 浏览器级真实 E2E 已闭环
|
||
- 当前剩余工作主要是提交边界整理与文档/工作树卫生收口，而非新的功能性 blocker
|
||
|
||
**边界说明：** 当前可以诚实宣称的是“本地可审计的后端/前端验证与浏览器级真实 E2E 已闭环”；不应夸大为“所有生产外部集成和完整上线材料都已全部闭环”。
|