IMTIM-Portal/docs/casdoor-setup.md

# Casdoor v3.18.0 配置手册

本文档详细说明如何配置本地Docker部署的Casdoor实例，以便与base-imtim门户应用集成。

---

## 目录

1. [访问Casdoor管理界面](#1-访问casdoor管理界面)
2. [创建组织](#2-创建组织)
3. [创建应用](#3-创建应用)
4. [配置认证方式](#4-配置认证方式)
5. [配置到base-imtim](#5-配置到base-imtim)
6. [测试登录流程](#6-测试登录流程)
7. [常见问题排查](#7-常见问题排查)

---

## 1. 访问Casdoor管理界面

### 1.1 确认Casdoor运行状态

```bash
docker ps | grep casdoor
```

### 1.2 访问管理后台

```
http://localhost:8000
```

### 1.3 登录

- **用户名**: `admin`
- **密码**: `123` (默认)

> ⚠️ 首次登录后请修改密码

---

## 2. 创建组织

1. 左侧导航栏 → **组织管理** → **组织**
2. 点击 **添加**
3. 填写:

| 字段 | 值 |
|------|------|
| 组织名称 | `imtim` |
| 显示名称 | `IMTIM Portal` |
| 密码类型 | `salt` |

4. 点击 **保存**

---

## 3. 创建应用

1. 左侧导航栏 → **应用管理** → **应用**
2. 点击 **添加**
3. 填写配置:

### 基本信息

| 字段 | 值 | 说明 |
|------|------|------|
| 名称 | `base-imtim` | 应用唯一标识 |
| 显示名称 | `IMTIM Portal` | 界面显示名称 |
| 组织 | `imtim` | 选择刚创建的组织 |

### 认证配置 (关键)

| 字段 | 值 | 说明 |
|------|------|------|
| **重定向URL** | `http://localhost:3000/api/auth/callback` | **必须一致** |
| 令牌格式 | `JWT` | |
| 令牌有效期 | `168` | 7天(小时) |

4. 点击 **保存**

5. **复制凭据**:
   - Client ID (如: `a129daf893d964c03bfb`)
   - Client Secret (如: `c3ecaa0d0e3f315d0a1a164087c88cbdf8324f00`)

---

## 4. 配置认证方式

### 4.1 创建测试用户

1. 左侧导航栏 → **用户管理** → **用户**
2. 点击 **添加**
3. 填写:
   - 组织: `imtim`
   - 用户名: 如 `imtim`
   - 显示名称
   - 密码
   - 邮箱 (可选)
4. 点击 **保存**

---

## 5. 配置到base-imtim

### 5.1 创建后端配置文件

```bash
cd backend
cp .env.example .env
```

### 5.2 编辑 .env 文件

```env
# Casdoor配置
CASDOOR_SERVER_URL=http://localhost:8000
CASDOOR_CLIENT_ID=你的ClientID
CASDOOR_CLIENT_SECRET=你的ClientSecret
CASDOOR_ORG_NAME=imtim
CASDOOR_APP_NAME=base-imtim
CASDOOR_REDIRECT_URI=http://localhost:3000/api/auth/callback

# JWT配置
JWT_SECRET=your-super-secret-jwt-key

# 应用配置
APP_PORT=3001
```

---

## 6. 测试登录流程

### 6.1 启动应用

```bash
# 后端
cd backend && npm run dev

# 前端 (新终端)
cd frontend && npm run dev
```

### 6.2 测试步骤

1. 访问 http://localhost:3000
2. 点击登录按钮
3. 跳转到Casdoor登录页面
4. 使用测试用户登录
5. 登录成功后应自动跳转到 /dashboard

---

## 7. 常见问题排查

### 7.1 重定向URL不匹配

**错误**: `redirect URI mismatch`

**解决**: 检查Casdoor应用配置中的重定向URL是否为 `http://localhost:3000/api/auth/callback`

### 7.2 获取用户信息失败

**错误**: `Authentication failed: Failed to get user info`

**解决**: Casdoor v3.x 使用 `/api/get-account` 而非 `/api/userinfo`

### 7.3 Client ID或Secret错误

**错误**: `invalid_client`

**解决**: 重新从Casdoor复制Client ID和Secret

### 7.4 Code已使用

**错误**: `authorization code has been used`

**说明**: OAuth code只能用一次，刷新页面重新登录

---

## 附录: Casdoor Docker部署

```yaml
version: '3.8'

services:
  casdoor:
    image: casbin/casdoor:v3.18.0
    ports:
      - "8000:8000"
    environment:
      - driverName=sqlite3
      - dataSourceName=casdoor.db
    volumes:
      - ./casdoor-data:/conf
```

---

**文档版本**: 1.1  
**最后更新**: 2026-04-16  
**适用Casdoor版本**: v3.18.0