Add authenticated login and SSO protection

README.zh-CN.md

@@ -138,6 +138,32 @@ npm run info
 | `/assets` | 历史任务与资产 |
 | `/settings` | 接口、引擎和服务配置 |
 
+## 账户登录 / SSO
+
+发布环境默认启用账户登录保护。Web 端支持 OAuth2 Authorization Code 和账号密码验证码两种登录方式：授权码模式会跳转认证中心，平台后端在 `/api/auth/callback` 用授权码换 token；账号密码方式会在本项目登录页提交账号、密码和图形验证码，由后端调用 `${AUTH_BASE}/oauth2/token` 的 password grant。两种方式都会通过 JWKS 本地验签 JWT，然后写入 HttpOnly 会话 cookie。
+
+认证中心客户端需要配置回调地址：
+
+```text
+https://你的域名/api/auth/callback
+```
+
+核心配置：
+
+| 变量 | 说明 |
+|------|------|
+| `ZHINIAN_AUTH_REQUIRED` | `auto` 默认策略；生产启用，本地可信开发可设 `0` |
+| `ZHINIAN_AUTH_BASE_URL` | 认证服务网关地址，例如 `https://<gateway-domain>/auth` |
+| `ZHINIAN_AUTH_CLIENT_ID` | OAuth2 客户端 ID，默认 `customPC` |
+| `ZHINIAN_AUTH_CLIENT_SECRET` | OAuth2 客户端密钥，只能保存在服务端 |
+| `ZHINIAN_AUTH_SCOPE` | 默认 `server` |
+| `ZHINIAN_AUTH_ISSUER` | JWT issuer，默认 `https://pig4cloud.com` |
+| `ZHINIAN_AUTH_SESSION_SECRET` | 本地会话签名密钥，使用长随机字符串 |
+
+受保护范围包括 `/create`、`/assets`、`/settings`、第一方生成/资产 API，以及本地 `/uploads/*` 和 `/generated-results/*` 文件。开放 `/api/v1/*` 仍使用 API Key，Worker 仍使用内部 token，不走浏览器 SSO。
+
+如果认证中心客户端没有加入 `security.ignore-clients`，账号密码登录会要求图形验证码；验证码图片由 `/api/auth/captcha` 代理 `${AUTH_BASE}/code/image` 获取。
+
 ## 引擎说明
 
 ### 图片生成
@@ -216,6 +242,11 @@ cp .env.example .env.local
 |------|------|
 | `APP_PORT` | Docker Compose 对外暴露端口，默认 `3000` |
 | `NEXT_PUBLIC_APP_URL` | 对外访问地址，用于生成回调/本地文件 URL |
+| `ZHINIAN_AUTH_REQUIRED` | 账户登录保护策略 |
+| `ZHINIAN_AUTH_BASE_URL` | 统一认证中心地址 |
+| `ZHINIAN_AUTH_CLIENT_ID` | OAuth2 客户端 ID |
+| `ZHINIAN_AUTH_CLIENT_SECRET` | OAuth2 客户端密钥 |
+| `ZHINIAN_AUTH_SESSION_SECRET` | 本地登录态签名密钥 |
 | `ZHINIAN_API_KEYS` | 开放 API Key，格式 `clientId:key,clientId2:key2` |
 | `ZHINIAN_INTERNAL_WORKER_TOKEN` | 内部 Worker tick 接口令牌 |
 | `ZHINIAN_WEBHOOK_SECRET` | Webhook 签名密钥，可选 |