云超服Agents 演示后端（pineagents-demo-server）

供 PineAgents 主后端认证转发的演示 FastAPI。主后端 src/pineagents/app/routers/auth.py 把所有 /api/auth/* 请求转发到本服务（PINEAGENTS_DEMO_BASE_URL，默认 http://127.0.0.1:8090）， 本服务只负责登录、注册、资料维护等演示接口。

• 框架：FastAPI + uvicorn，环境由 uv 管理
• 数据：本地 JSON 文件（data/ 目录），首次启动从 data/seed/ 种子数据初始化
• 演示账号：pine / 123456
• 下阶段：依据 JSON 文件的结构（见下文「JSON 格式与未来数据库映射」）设计并替换为真实数据库

---

快速开始

# 1. 安装依赖（首次）
uv sync

# 2. 启动服务（默认 127.0.0.1:8090）
uv run uvicorn app.main:app --host 127.0.0.1 --port 8090 --reload
# 或
uv run python -m app

# 3. 运行测试
uv run pytest

启动后接口文档：http://127.0.0.1:8090/docs

目录结构

PineAgentsServer/
├── pyproject.toml          # uv 项目配置（依赖、构建、pytest）
├── app/
│   ├── main.py             # FastAPI 应用入口（lifespan 初始化 JSON 数据库）
│   ├── config.py           # 端口 / 数据目录 / 令牌有效期等配置
│   ├── models.py           # Pydantic 请求/响应模型（与主后端转发模型一致）
│   ├── security.py         # 密码哈希（加盐 SHA-256）与令牌生成
│   ├── storage.py          # JSON 存储引擎：一个文件 = 一张表
│   ├── repositories.py     # 数据访问层：UserRepository / TokenRepository / Database
│   ├── dependencies.py     # get_db / get_current_user（Bearer 校验）
│   └── routers/auth.py     # /auth/* 路由
├── data/
│   ├── seed/demo_users.json  # 种子数据（提交到仓库）
│   ├── users.json            # 运行时生成（已 gitignore，等同数据库文件）
│   └── tokens.json           # 运行时生成（已 gitignore）
└── tests/test_auth.py       # 接口端到端测试

接口一览

方法	路径	说明	鉴权
POST	/auth/login	登录，成功返回令牌 + 资料	否
POST	/auth/register	注册唯一账户（演示端已有用户 → 403）	否
GET	/auth/status	认证开关 / 是否已有用户	否
GET	/auth/verify	校验 Bearer 令牌 → {valid, username}	否（无效返回 401）
GET	/auth/me	当前用户完整资料	Bearer
POST	/auth/update-profile	更新资料 / 用户名 / 密码，返回最新资料	Bearer
POST	/auth/revoke-token	吊销单个令牌（省略则吊销当前）	Bearer
POST	/auth/revoke-all-tokens	吊销全部令牌	Bearer
GET	/health	健康检查	否

update-profile 规则：

• 仅改资料字段（nickname/account/company/room/avatar/company_avatar）时无需密码、不重签令牌；
• 修改用户名/密码时必须提供正确的 current_password，成功后吊销该用户其余会话并重签令牌随响应返回；
• 空 new_username/new_password → 400；没有任何可更新内容 → 400 "Nothing to update"；
• 当前密码错误 → 401 "Current password is incorrect"。

JSON 格式与未来数据库映射

设计原则：文件名 = 表名，数组元素 = 一行，字段 = 一列。下阶段把 storage.py + repositories.py 换成 SQL/ORM 实现即可，路由与业务逻辑不变。

data/users.json（用户表）

首次启动由 data/seed/demo_users.json 生成：种子里只有明文 password， 初始化时立即哈希并落盘为 password_hash + password_salt，磁盘上不保留明文。

[
  {
    "id": "u_demo_01",
    "username": "pine",
    "password_hash": "cf6238f4...d854ed7",
    "password_salt": "e23eee00389d5954a88fcd21cef9176f",
    "nickname": "云超服小助手",
    "account": "云超服演示账号",
    "company": "云超服科技",
    "room": "1001",
    "avatar": "",
    "company_avatar": "",
    "created_at": "2026-08-02T12:42:36+00:00",
    "updated_at": "2026-08-02T12:42:36+00:00"
  }
]

JSON 字段	未来数据库列	类型（建议）	说明
id	id	TEXT PK	用户主键
username	username	TEXT UNIQUE NOT NULL	登录名
password_hash	password_hash	TEXT NOT NULL	密码哈希
password_salt	password_salt	TEXT NOT NULL	密码盐
nickname/account/company/room/avatar/company_avatar	同名列	TEXT DEFAULT ''	演示资料字段
created_at / updated_at	同名列	TIMESTAMPTZ NOT NULL	时间戳

data/tokens.json（访问令牌/会话表）

[
  {
    "id": "tok_46388dab7a5333ff6c8a5a7f",
    "token": "01Sek11n8G...Intk",
    "user_id": "u_demo_01",
    "username": "pine",
    "created_at": "2026-08-02T12:42:39+00:00",
    "expires_at": "2026-08-09T12:42:39+00:00",
    "revoked": false
  }
]

JSON 字段	未来数据库列	类型（建议）	说明
id	id	TEXT PK	令牌记录主键
token	token	TEXT UNIQUE NOT NULL	不透明令牌串
user_id	user_id	TEXT FK → users.id	所属用户
username	username	TEXT	冗余用户名（便于查询/展示）
created_at	created_at	TIMESTAMPTZ NOT NULL	签发时间
expires_at	expires_at	TIMESTAMPTZ NOT NULL	过期时间（-1/0 = 永久 ≈ 100 年）
revoked	revoked	BOOLEAN DEFAULT FALSE	是否已吊销

配置项（环境变量）

变量	默认值	说明
PINEAGENTS_DEMO_HOST	127.0.0.1	监听地址
PINEAGENTS_DEMO_PORT	8090	监听端口（与主后端 DEMO_API_BASE_URL 一致）
PINEAGENTS_DEMO_DATA_DIR	<项目根>/data	JSON 数据目录
PINEAGENTS_DEMO_AUTH_ENABLED	true	认证开关（true/1/yes）

与本项目（PineAgents）的对接

主后端已把 /api/auth/login|register|status|verify|me|update-profile|revoke-token|revoke-all-tokens 转发到本服务。联调时：

1. 本服务监听 127.0.0.1:8090；
2. 主后端 constant.py 中 DEMO_API_BASE_URL 指向它（或设 PINEAGENTS_DEMO_BASE_URL）；
3. 前端用 pine / 123456 登录即可。

测试（tests/test_auth.py）使用临时目录的 JSON 数据库，不会污染 data/。