long-agent
a3e090e821
- webhook_service_test.go: isPrivateIP, isSafeURL, computeHMAC - request_metadata_test.go: context functions - classified_error_test.go: error types - config_defaults_test.go: password reset/SMS defaults - email_config_test.go: email code defaults - auth_runtime_test.go: isUserNotFoundError Service coverage: 11.2% -> 14.7%
120 lines
2.7 KiB
Markdown
120 lines
2.7 KiB
Markdown
# User Management System (UMS)
|
||
|
||
企业级用户管理系统，支持 RBAC 角色权限管理、多因素认证、设备信任和安全审计。
|
||
|
||
## 快速开始
|
||
|
||
### 前置依赖
|
||
|
||
- Go 1.21+
|
||
- Node.js 18+
|
||
- SQLite（默认，无需安装）
|
||
|
||
### 启动后端
|
||
|
||
```bash
|
||
# 复制环境配置
|
||
cp .env.example .env
|
||
# 编辑 .env 填入必要配置（JWT_SECRET, DEFAULT_ADMIN_PASSWORD 等）
|
||
|
||
# 启动服务
|
||
go run ./cmd/server
|
||
```
|
||
|
||
服务启动后访问 `http://localhost:8080/api/v1/auth/bootstrap` 初始化管理员账号。
|
||
|
||
### 启动前端
|
||
|
||
```bash
|
||
cd frontend/admin
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
.
|
||
├── cmd/server/ # 后端入口
|
||
├── internal/ # 后端代码
|
||
│ ├── api/handler/ # HTTP 处理器
|
||
│ ├── api/middleware/ # 中间件（认证、权限、限流）
|
||
│ ├── auth/ # 认证服务（JWT/SSO）
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── service/ # 业务逻辑层
|
||
│ └── domain/ # 领域模型
|
||
├── frontend/admin/ # 管理后台前端
|
||
├── configs/ # 配置文件
|
||
├── docs/ # 详细文档
|
||
└── data/ # SQLite 数据库目录
|
||
```
|
||
|
||
## 核心功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 用户管理 | 注册、登录、CRUD、批量操作 |
|
||
| RBAC | 角色继承、权限细粒度控制 |
|
||
| TOTP | Google Authenticator 二次验证 |
|
||
| 设备信任 | 信任设备免二次验证 |
|
||
| 登录日志 | 完整操作审计 |
|
||
| Webhook | 事件通知（user.created/deleted 等）|
|
||
| SSO | CAS 协议支持 |
|
||
|
||
## 环境变量
|
||
|
||
关键配置项（详见 `.env.example`）：
|
||
|
||
| 变量 | 说明 | 必填 |
|
||
|------|------|------|
|
||
| `JWT_SECRET` | JWT 签名密钥 | 是 |
|
||
| `DEFAULT_ADMIN_EMAIL` | 初始管理员邮箱 | 是 |
|
||
| `DEFAULT_ADMIN_PASSWORD` | 初始管理员密码 | 是 |
|
||
| `SMTP_*` | 邮件服务配置 | 是（邮件功能）|
|
||
| `SMS_*` | 短信服务配置 | 否 |
|
||
|
||
## API 文档
|
||
|
||
完整 API 规范：`docs/API.md`
|
||
|
||
认证流程：
|
||
```
|
||
1. POST /api/v1/auth/register # 注册用户
|
||
2. POST /api/v1/auth/login # 登录获取 Token
|
||
3. POST /api/v1/auth/refresh # 刷新 Token
|
||
```
|
||
|
||
## 开发命令
|
||
|
||
```bash
|
||
# 构建
|
||
go build ./cmd/server
|
||
|
||
# 测试
|
||
go test ./internal/... -cover
|
||
|
||
# 前端构建
|
||
cd frontend/admin && npm run build
|
||
|
||
# Docker 构建
|
||
docker build -t ums .
|
||
```
|
||
|
||
## 部署
|
||
|
||
- 开发部署：`docs/DEPLOYMENT.md`
|
||
- 生产部署：`DEPLOY_GUIDE.md`
|
||
- 运行手册：`docs/guides/` 目录下的 7 个 Runbook
|
||
|
||
## 测试覆盖率
|
||
|
||
```
|
||
api/handler 15.6%
|
||
api/middleware 21.5%
|
||
auth 28.1%
|
||
repository 47.2%
|
||
internal/middleware 65.4%
|
||
```
|
||
|
||
目标：80%+
|