4an-workorder/CASDOOR_SETUP.md

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 或系统环境变量）中添加以下配置：

# 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 依赖：

pip install -r requirements.txt

主要依赖包括：

• requests: 用于与 Casdoor API 通信
• Flask-Login: 用于会话管理
• 其他项目依赖

第四步：在 Casdoor 中创建用户

1. 创建用户

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

2. 关联用户到应用

   • 在用户详情页面，确保用户属于正确的组织
   • 用户登录后会自动同步到本地数据库

第五步：测试登录

1. 启动应用

   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 同步到本地数据库，确保数据一致性