189 lines
6.1 KiB
Markdown
189 lines
6.1 KiB
Markdown
# 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 同步到本地数据库，确保数据一致性
|
||
|