# 认证与订阅体系（Casdoor）

**方向决策（2026-10）**：全量统一到 Casdoor；订阅数据模型走 Casdoor 原生
`Plan` / `Subscription` / `Payment`。Keycloak 与独立 Go `billing-service`
逐步退役或降级为报表层。

## 生产拓扑

```
https://auth.yaogal.com          ← 唯一 OIDC 入口（issuer）
   │  TLS: /etc/letsencrypt/live/yaogal.com/
   │       SAN: yaogal.com, www.yaogal.com, auth.yaogal.com
   │       到期 2027-01-02，certbot timer 自动续期
   ▼
sl-entry  nginx 反代（sites-enabled/auth-prod，手工维护）
   ▼
sl-01  192.168.0.134:8000  Casdoor 4.14.0 + Postgres 17（docker compose）
```

- `CASDOOR_ORIGIN=https://auth.yaogal.com`，`CASDOOR_ORIGIN_FRONTEND` **同值**
  （否则 OIDC discovery 的 `authorization_endpoint` 会指错域名）。
- sl-entry 的 `default-404` 配置了 `ssl_reject_handshake on;`：任何未匹配的 SNI
  在 TLS 层直接拒绝（包括旧的 `*.hidden.testing.yaogal.com`）。
- Casdoor DB 现状：只保留 `app-built-in`（管理 UI）与 org `yaogal`；
  `account-portal` app 与自定义 plans 已删除。
- **account-site 不再部署**（Casdoor 自带 admin UI 够用）；仓库保留，见
  [](repos/yaogal)。

## 部署与 bootstrap

- 镜像与编排：`repos/yaogal/docker-images/casdoor/`（compose + `.env`）；
  镜像是 **`casbin/casdoor`**（Docker Hub 官方 repo，不是 `casdoor/casdoor`）。
- `init/init.sh` 幂等 bootstrap：登录 admin → 建 org `yaogal` → 建 application →
  可选 seed plans（`init/seed/plan-{free,pro}.json`）→ 写 `.client-id`。
- playbook：`site-deploy/playbooks/casdoor.md`（部署）与 `auth-proxy.md`
  （sl-entry 反代的手工文档）。
- 本地 smoke test 已通过（2026-10-04）：discovery / JWKS / PKCE S256 / authorize
  端点正常，issuer 无 `/realms/` 前缀。

## 接入方式（应用侧）

统一接入指南：**`site-deploy/docs/oauth-integration.md`**（P1 文档，覆盖
discovery、scopes、client 命名、PKCE flow、JS/TS/Go/ArkTS 四份片段、JWKS 校验
规则、Keycloak→Casdoor 字段映射、常见坑）。速查要点：

- 协议：OIDC Authorization Code + **PKCE（S256）**；TOTP 与三方绑定由 Casdoor 侧支持。
- SPA 参考实现：`account-site/scripts/inject-config.mjs` —— 构建前把
  `CASDOOR_ORIGIN` 与 `.client-id` 注入 `public/app-config.json`，
  检测到 `/realms/` 残留直接构建失败。
- issuer 校验：无 `/realms/` 前缀（区别于 Keycloak）。

## 踩坑记录（smoke test 期间发现，均已回修）

| 坑 | 结论 |
|---|---|
| 镜像命名空间 | `casbin/casdoor` |
| 默认 admin 用户名 | `admin`（小写） |
| login API 请求体 | 必须带 `method:"password"` + `signinMethod:"Account"` + `username` |
| `.env` 含空格的值 | 必须加引号（`set -a; source` 会把裸值当命令） |
| sl-01 无外网直连 | docker `registry-mirrors`：`docker.1panel.live` / `dockerproxy.net` 可用 |

## 已知遗留（安全相关）

```{danger}
Casdoor admin 密码仍是种子默认 `admin / 123`，且管理 UI 经 auth.yaogal.com
公网可达。**尽快**：登录 → User Management → admin → 修改密码，并同步
`casdoor/.env` 的 `CASDOOR_ADMIN_PASSWORD`。
```