# Casdoor 集成配置指南

本文档将指导您如何配置 Casdoor 作为项目的登录认证系统。

## 前置条件

1. 已通过 1Panel 部署 Casdoor 服务
2. Casdoor 服务可以正常访问
3. 拥有 Casdoor 管理员权限

## 第一步：在 Casdoor 中创建应用

1. **登录 Casdoor 管理界面**
   - 访问您的 Casdoor 地址（例如：`http://your-server:8000`）
   - 使用管理员账户登录（默认：`admin` / `123`）

2. **创建应用（Application）**
   - 进入 "Applications" 页面
   - 点击 "Add" 按钮创建新应用
   - 填写以下信息：
     - **Name**: 应用名称（例如：`4an-app`）
     - **Display name**: 显示名称（例如：`4AN 工单管理系统`）
     - **Organization**: 选择组织（默认：`built-in`）
     - **Enable password**: 是否启用密码登录（根据需要选择）
     - **Enable sign up**: 是否允许注册（根据需要选择）
   
3. **配置回调 URL（Redirect URI）**
   - 在应用配置中找到 "Redirect URLs" 或 "Redirect URI"
   - 添加您的应用回调地址，例如：
     ```
     http://your-app-server:18061/callback
     ```
   - 如果有多个环境，可以添加多个回调地址

4. **记录应用凭证**
   - 创建应用后，Casdoor 会生成：
     - **Client ID**: 客户端 ID
     - **Client Secret**: 客户端密钥
   - 请妥善保存这些信息，后续配置需要使用

## 第二步：配置项目环境变量

在您的环境变量文件（`.env` 或系统环境变量）中添加以下配置：

```bash
# Casdoor 配置
CASDOOR_ENDPOINT=http://your-casdoor-server:8000
CASDOOR_CLIENT_ID=your_client_id_here
CASDOOR_CLIENT_SECRET=your_client_secret_here
CASDOOR_ORGANIZATION_NAME=built-in
CASDOOR_APPLICATION_NAME=your_app_name
CASDOOR_REDIRECT_URI=http://your-app-server:18061/callback
```

### 配置说明

- `CASDOOR_ENDPOINT`: Casdoor 服务的完整地址（不包含路径）
- `CASDOOR_CLIENT_ID`: 在 Casdoor 中创建应用时获得的 Client ID
- `CASDOOR_CLIENT_SECRET`: 在 Casdoor 中创建应用时获得的 Client Secret
- `CASDOOR_ORGANIZATION_NAME`: 组织名称（默认：`built-in`）
- `CASDOOR_APPLICATION_NAME`: 应用名称（与 Casdoor 中创建的应用名称一致）
- `CASDOOR_REDIRECT_URI`: 回调地址，必须与 Casdoor 应用中配置的 Redirect URI 完全一致

## 第三步：安装依赖

确保已安装所有必要的 Python 依赖：

```bash
pip install -r requirements.txt
```

主要依赖包括：
- `requests`: 用于与 Casdoor API 通信
- `Flask-Login`: 用于会话管理
- 其他项目依赖

## 第四步：在 Casdoor 中创建用户

1. **创建用户**
   - 进入 Casdoor 的 "Users" 页面
   - 点击 "Add" 创建新用户
   - 填写用户信息：
     - **Name**: 用户名（唯一标识）
     - **Display name**: 显示名称
     - **Email**: 邮箱（可选）
     - **Phone**: 手机号（建议填写，用于与本地用户表关联）
     - **Password**: 密码
     - **Organization**: 选择组织

2. **关联用户到应用**
   - 在用户详情页面，确保用户属于正确的组织
   - 用户登录后会自动同步到本地数据库

## 第五步：测试登录

1. **启动应用**
   ```bash
   python app/app.py
   # 或使用 uwsgi/supervisor 启动
   ```

2. **访问登录页面**
   - 访问 `http://your-app-server:18061/login`
   - 您应该看到两个登录选项：
     - "使用 Casdoor 登录" 按钮（如果配置了 Casdoor）
     - 手机号登录表单（备用方案）

3. **测试 Casdoor 登录**
   - 点击 "使用 Casdoor 登录" 按钮
   - 应该重定向到 Casdoor 登录页面
   - 使用 Casdoor 中的用户账户登录
   - 登录成功后应该重定向回应用并自动登录

## 用户信息同步

当用户通过 Casdoor 首次登录时，系统会：

1. 从 Casdoor 获取用户信息
2. 检查本地数据库中是否存在该用户（通过手机号匹配）
3. 如果不存在，创建新用户记录
4. 如果存在，更新用户信息（姓名、支局、角色等）

用户信息映射：
- `phone`: 从 Casdoor 的 `phone` 或 `phoneNumber` 字段获取
- `name`: 从 Casdoor 的 `name` 或 `displayName` 字段获取
- `branch`: 从 Casdoor 的 `affiliation` 字段获取
- `role`: 从 Casdoor 的 `type` 字段获取

## 故障排查

### 问题：点击 Casdoor 登录按钮没有反应或报错

**解决方案**：
1. 检查环境变量是否正确配置
2. 检查 `CASDOOR_ENDPOINT` 是否可以访问
3. 检查 `CASDOOR_CLIENT_ID` 和 `CASDOOR_CLIENT_SECRET` 是否正确
4. 查看应用日志获取详细错误信息

### 问题：登录后回调失败

**解决方案**：
1. 确保 `CASDOOR_REDIRECT_URI` 与 Casdoor 应用中配置的完全一致
2. 检查回调地址是否可以从 Casdoor 服务器访问
3. 检查防火墙和网络配置

### 问题：无法获取用户信息

**解决方案**：
1. 检查 Casdoor 应用配置中的 Scope 是否包含 `openid profile email phone`
2. 检查用户是否有正确的权限
3. 查看应用日志中的详细错误信息

### 问题：用户信息同步失败

**解决方案**：
1. 确保 Casdoor 用户信息中包含手机号（phone）
2. 检查数据库连接是否正常
3. 查看应用日志获取详细错误信息

## 安全建议

1. **保护 Client Secret**
   - 不要将 `CASDOOR_CLIENT_SECRET` 提交到代码仓库
   - 使用环境变量或密钥管理服务存储敏感信息

2. **使用 HTTPS**
   - 生产环境建议使用 HTTPS
   - 更新 `CASDOOR_ENDPOINT` 和 `CASDOOR_REDIRECT_URI` 为 HTTPS 地址

3. **定期更新密码**
   - 定期更新 Casdoor 管理员密码
   - 定期轮换 Client Secret

4. **监控日志**
   - 定期检查应用日志，关注认证失败的情况
   - 设置告警机制

## 更多信息

- Casdoor 官方文档：https://casdoor.org/docs/overview
- Casdoor GitHub：https://github.com/casbin/casdoor

## 注意事项

1. 如果未配置 Casdoor（未设置 `CASDOOR_CLIENT_ID`），系统会自动使用原有的手机号登录方式
2. 两种登录方式可以并存，用户可以选择使用哪种方式登录
3. 用户信息会从 Casdoor 同步到本地数据库，确保数据一致性