认证与 License

GraphForge 后端通过两道关门保护 API：License 校验（系统启动期）+ JWT 鉴权（每个请求）。集成方关注后者；License 由部署运维负责。

JWT 登录流程

1. 用 username + password 换取 Token

curl -X POST https://<your-host>/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<your-user>","password":"<your-password>"}'

响应：

{
  "user_id": 2,
  "username": "<your-user>",
  "is_admin": false,
  "must_change_password": false,
  "token": "eyJhbGc..."
}

token TTL 默认 7 天（JWT_EXPIRE_SECONDS 可配）。

2. 后续所有请求带 `Authorization` 头

curl https://<your-host>/api/graphs \
  -H 'Authorization: Bearer <token>'

3. 验证 Token 是否仍有效

调 GET /api/auth/me，返 200 + 用户信息即仍有效；401 即失效（密码改了 / TTL 到 / Key rotation）。

API Key（替代 JWT 的长期凭证）

JWT 适合短期会话；服务对服务集成推荐用 API Key：

用 JWT 登录后，调 POST /api/api-keys 创建 Key（指定授权图谱 + 速率限制 + 过期时间）
响应的 raw_key 仅一次显示，立刻保存到密码管理器
后续请求改用 X-API-Key: <raw_key> 头（不需要再换 JWT）

详见 API Reference → api-keys。

速率限制

防止误用与 DDoS：

端点类	限制
`/auth/login`	10/min/IP
`/auth/register` + `/auth/password`	5/min/IP
`/graphs/{id}/query`	30/min/user
`/ingestion/jobs/{id}/run`	30/min/user
其他大部分	60/min/user

触发返 429 Too Many Requests，等 60s 重试即可。

must_change_password 强制改密

系统初始 admin / 由 admin 重置的用户密码格式为 <username>1q2w3e4r，登录后响应里 must_change_password=true。前端 UI 会被 MustChangePasswordGate 拦到 /settings/password?force=true；集成方走 API 时需调 PUT /api/auth/password 改密后才能正常用其他接口（部分会被服务端拦 403）。

申请试用 License

GraphForge 启用 License 模式时（LICENSE_CHECK_ENABLED=true），后端启动会向 License Server (license.yrules.com) 校验。集成方拿到的服务实例已经配好 License；如果需要自建实例：

邮件 marketing@yrules.com 申请试用，说明部署环境（联网 / 离线）+ 客户名
在线模式 → 拿到 LICENSE_KEY 写入 .env
离线模式 → 拿到 .lic 文件，配 LICENSE_FILE 环境变量
详见产品 → License 或联系我们