central-platform/README.md

Center Platform

轻量级统一认证中心，为多个业务系统提供账号管理、登录认证与会话验证 API。

特性

• FastAPI 异步接口与统一响应协议
• MySQL 持久化用户数据，Argon2id 安全存储密码
• Redis 管理具有过期时间的 Opaque Token 会话
• 支持用户名或邮箱登录
• 校验受信任的 from_url，便于登录后返回来源系统
• Alembic 数据库迁移、pytest 测试与 Ruff 代码检查

技术栈

Python 3.11+ · FastAPI · SQLAlchemy 2.0 · MySQL · Redis · Alembic · uv

快速开始

确保本机已安装 MySQL 8+、Redis 6+ 和 uv，然后执行：

uv sync
Copy-Item .env.example .env
uv run alembic upgrade head
uv run fastapi dev app/main.py --port 8100

启动前请在 .env 中配置数据库连接、Redis 连接及可信回跳来源。DATABASE_URL、REDIS_URL 和 REDIS_KEY_PREFIX 为必填项，缺失时应用会拒绝启动。将 REGISTRATION_ENABLED 设置为 false 可关闭公开注册接口。完整配置和注释见 .env.example。

服务默认运行在 http://127.0.0.1:8100，交互式 API 文档 http://127.0.0.1:8100/docs

API

方法	路径	说明
GET	/health	检查服务、依赖及注册开关状态
POST	/api/auth/register	注册用户
POST	/api/auth/login	登录并签发 Token
POST	/api/auth/verify	验证 Token 与回跳地址
POST	/api/auth/logout	注销当前 Token
GET	/api/users/me	获取当前用户信息

登录示例：

curl -X POST http://127.0.0.1:8100/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"account":"alice","password":"password123","from_url":"https://app.example.com/callback"}'

受保护接口使用 Authorization: Bearer <token> 请求头。

已登录回跳需要把待校验地址交给后端，并且只使用响应中的 data.from_url：

curl -X POST http://127.0.0.1:8100/api/auth/verify \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"from_url":"https://app.example.com/callback"}'

响应协议

所有接口返回统一结构：

{
  "code": 0,
  "data": {},
  "msg": "请求成功"
}

成功响应使用 HTTP 200 和 code=0。失败时 HTTP 状态码与 code 一致，data 为 null。当前错误码包括 400、401、403、 429 和 500。

开发

uv run pytest
uv run ruff check app migrations tests
uv run ruff format --check app migrations tests

创建数据库迁移：

uv run alembic revision --autogenerate -m "描述"
uv run alembic upgrade head

项目结构

app/api/          HTTP 接口与依赖
app/service/      业务逻辑
app/repository/   数据访问
app/model/        SQLAlchemy 模型
app/schema/       请求与响应模型
app/core/         配置、数据库、Redis 与安全组件
migrations/       Alembic 数据库迁移