配置参考

以下参考涵盖了 Paideia LMS 所有支持的配置选项。Paideia LMS 可以通过环境变量、.env 文件和 paideia.config.json 文件进行配置。

配置优先级

Paideia LMS 按以下优先级顺序从多个来源加载配置（优先级高的会覆盖优先级低的）：

1. paideia.config.json - 系统配置文件（系统设置的优先级最高）
2. .env 文件 - 本地环境变量（优先级高于托管环境）
3. 托管环境变量 - 由托管平台设置的变量（优先级最低）

环境变量

环境变量可以在托管环境中设置，也可以在运行应用程序的路径下的 .env 文件中设置。.env 文件的优先级高于托管环境变量。

数据库配置

DATABASE_URL

类型: string
必需: true
敏感: true

数据库连接 URL。这是 Paideia LMS 连接数据库所必需的。

DATABASE_URL=postgresql://user:password@localhost:5432/paideia

服务器配置

PORT

类型: number
必需: false
敏感: true
默认值: 3001

Paideia LMS 后端服务器的端口号。

PORT=3001

FRONTEND_PORT

类型: number
必需: false
敏感: true
默认值: 3000

Paideia LMS 前端应用程序的端口号。

FRONTEND_PORT=3000

存储配置（S3/MinIO）

S3_URL

类型: string
必需: true
敏感: true

S3 兼容存储服务的 URL 端点（例如 MinIO、AWS S3）。

S3_URL=https://s3.amazonaws.com

S3_ACCESS_KEY

类型: string
必需: true
敏感: true

S3 兼容存储服务的访问密钥 ID。

S3_ACCESS_KEY=your-access-key

S3_SECRET_KEY

类型: string
必需: true
敏感: true

S3 兼容存储服务的秘密访问密钥。

S3_SECRET_KEY=your-secret-key

S3_REGION

类型: string
必需: false
敏感: true
默认值: "us-east-1"

S3 兼容存储服务的区域。

S3_REGION=us-east-1

S3_BUCKET

类型: string
必需: false
敏感: true

S3 兼容存储服务的存储桶名称。存储桶名称必须与 MinIO 配置中的存储桶名称匹配。

S3_BUCKET=paideia-media

S3_ENDPOINT_URL

类型: string
必需: true
敏感: true

S3 兼容存储服务的端点 URL（不包含存储桶名称）。这应该与 MinIO 配置中的端点 URL 匹配。

S3_ENDPOINT_URL=https://storage.example.com

身份验证和安全

PAYLOAD_SECRET

类型: string
必需: true
敏感: true

Payload CMS 用于身份验证和加密的密钥。这应该是一个长且随机生成的字符串。

PAYLOAD_SECRET=your-secret-key-here

电子邮件配置

SMTP_HOST

类型: string
必需: false
敏感: true

用于发送电子邮件的 SMTP 服务器主机名。

SMTP_HOST=smtp.example.com

SMTP_USER

类型: string
必需: false
敏感: true

用于身份验证的 SMTP 用户名。

SMTP_USER=your-smtp-username

SMTP_PASS

类型: string
必需: false
敏感: true

用于身份验证的 SMTP 密码。

SMTP_PASS=your-smtp-password

RESEND_API_KEY

类型: string
必需: false
敏感: true

Resend 电子邮件服务的 API 密钥（SMTP 的替代方案）。

RESEND_API_KEY=re_your-api-key

EMAIL_FROM_ADDRESS

类型: string
必需: false
敏感: false
默认值: "info@paideialms.com"

用作系统电子邮件”发件人”地址的电子邮件地址。

EMAIL_FROM_ADDRESS=noreply@yourdomain.com

EMAIL_FROM_NAME

类型: string
必需: false
敏感: false
默认值: "Paideia LMS"

用作系统电子邮件”发件人”名称的显示名称。

EMAIL_FROM_NAME=Your School Name

系统模式

SANDBOX_MODE

类型: string
必需: false
敏感: false
默认值: "0"

启用沙盒模式以进行开发和测试。启用时（"1" 或 "true"），系统将：

• 使用 seed.json 中的种子数据在服务器启动时自动重置数据库
• 通过 cron 作业安排每日数据库重置（午夜）
• 通过 paideia sandbox reset CLI 命令提供手动重置功能

零停机时间重置: 沙盒重置过程通过选择性删除用户数据同时保留系统表（作业日志、迁移等）来实现零停机时间。应用程序在重置过程中继续正常运行，这与删除整个数据库并导致停机的 migrate fresh 不同。

SANDBOX_MODE=1

零停机时间

当沙盒模式启用时，数据库重置会保留系统表（payload-jobs、payload-jobs-log、payload-migrations 等），同时仅删除用户数据。这允许应用程序在重置期间继续运行，实现零停机时间。

仅限开发和测试

沙盒模式专为开发和测试环境设计。它永远不应在生产环境中启用，因为它会按每日计划自动删除所有用户数据。

CORS 配置

CORS_ORIGINS

类型: string
必需: false
敏感: false
默认值: ""

允许的 CORS 来源的逗号分隔列表。如果为空，则默认为前端和后端端口的 localhost URL。使用 "*" 允许所有来源（不推荐用于生产环境）。

CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

特殊值:

• 空字符串：默认为 http://localhost:3000 和 http://localhost:3001
• "*"：允许所有来源
• 逗号分隔的 URL：允许特定来源

CSRF 配置

CSRF_ORIGINS

类型: string
必需: false
敏感: false
默认值: ""

允许的 CSRF 来源的逗号分隔列表。如果为空，则默认为 localhost 前端端口和 “localhost” 主机名。出于安全原因，不支持通配符 "*"。

CSRF_ORIGINS=http://localhost:3000,https://yourdomain.com

特殊值:

• 空字符串：默认为 http://localhost:3000 和 "localhost"
• 逗号分隔的 URL/域名：允许特定来源

种子数据配置

启用 SANDBOX_MODE 时，Paideia LMS 可以使用 seed.json 文件中的种子数据来填充数据库的初始测试数据。此文件应放置在运行应用程序的路径下。

重置行为: 当沙盒模式重置数据库时（启动时或通过 cron 作业），它使用零停机时间方法：

• 保留系统表（payload-jobs、payload-jobs-log、payload-migrations 等）
• 仅选择性删除用户数据（用户、课程、注册、提交等）
• 使用 seed.json 中的新数据重新填充数据库
• 允许应用程序在重置过程中继续运行

种子数据架构

seed.json 文件必须遵循以下结构：

{
  "admin": {
    "email": "admin@example.com",
    "password": "password123",
    "firstName": "Admin",
    "lastName": "User"
  },
  "users": {
    "student": {
      "email": "student@example.com",
      "password": "password123",
      "firstName": "Student",
      "lastName": "User"
    },
    "teacher": {
      "email": "teacher@example.com",
      "password": "password123",
      "firstName": "Teacher",
      "lastName": "User"
    },
    "ta": {
      "email": "ta@example.com",
      "password": "password123",
      "firstName": "Teaching",
      "lastName": "Assistant"
    },
    "additionalStudents": [
      {
        "email": "student2@example.com",
        "password": "password123",
        "firstName": "Student",
        "lastName": "Two"
      }
    ]
  },
  "courses": [
    {
      "title": "计算机科学导论",
      "description": "适合初学者的课程",
      "slug": "intro-cs",
      "status": "published"
    }
  ],
  "modules": {
    "page": {
      "title": "欢迎页面",
      "description": "欢迎页面模块",
      "content": "# 欢迎"
    },
    "additional": [
      {
        "type": "quiz",
        "title": "测验 1",
        "description": "第一个测验",
        "status": "published",
        "instructions": "回答所有问题",
        "points": 100,
        "timeLimit": 60
      }
    ]
  },
  "sections": [
    {
      "title": "第 1 周",
      "description": "介绍"
    }
  ],
  "enrollmentStatuses": ["active", "inactive", "completed"]
}

种子数据字段

admin

类型: object
必需: true

要创建的管理员用户账户。

• email - 管理员电子邮件地址
• password - 管理员密码
• firstName - 管理员名字
• lastName - 管理员姓氏

users

类型: object
必需: true

用于测试的预定义用户账户。

• student - 默认学生账户
• teacher - 默认教师账户
• ta - 默认助教账户
• additionalStudents - 附加学生账户数组

每个用户对象需要：

• email - 用户电子邮件地址
• password - 用户密码
• firstName - 用户名字
• lastName - 用户姓氏

courses

类型: array
必需: true

要创建的课程数组。

每个课程对象需要：

• title - 课程标题
• description - 课程描述
• slug - 课程 URL 别名
• status - 课程状态："published"、"draft" 或 "archived"

modules

类型: object
必需: true

用于测试的模块。

• page - 默认页面模块
  • title - 模块标题
  • description - 模块描述
  • content - 模块内容（markdown）
• additional - 附加模块数组

每个附加模块可以是以下之一：

• 页面 (type: "page")
  • title、description、status、content
• 测验 (type: "quiz")
  • title、description、status、instructions、points、timeLimit
• 作业 (type: "assignment")
  • title、description、status、instructions、dueDate、maxAttempts
• 讨论 (type: "discussion")
  • title、description、status、instructions、minReplies、threadSorting
• 白板 (type: "whiteboard")
  • title、description、status

sections

类型: array
必需: true

要创建的课程部分数组。

每个部分对象需要：

• title - 部分标题
• description - 部分描述

enrollmentStatuses

类型: array
必需: true

要使用的注册状态数组。有效值："active"、"inactive"、"completed"

系统配置文件

对于复杂和结构化的设置（通常是系统配置），Paideia LMS 从运行应用程序的路径下的 paideia.config.json 文件中读取。

配置文件优先级

paideia.config.json 文件对系统设置具有最高优先级。此文件中定义的值将：

• 始终覆盖数据库中存储的值
• 锁定编辑字段在 UI 中 - 管理员无法更改在配置文件中定义的设置

例如，如果系统名称在 paideia.config.json 中定义，系统名称输入字段将在 UI 中禁用，即使管理员也无法更改它。

示例配置文件

{
  "systemName": "我的学校 LMS",
  "featureFlags": {
    "enableNewFeature": true,
    "enableBetaFeatures": false
  },
  "systemSettings": {
    "maxFileSize": 10485760,
    "allowedFileTypes": ["pdf", "doc", "docx"]
  }
}

配置文件行为

当在 paideia.config.json 中定义设置时：

• 从文件读取设置值
• 在 UI 中锁定设置（输入字段被禁用）
• 管理员无法通过 UI 覆盖值
• 配置文件值优先于数据库值

这确保了关键系统设置可以通过版本控制的配置文件进行管理，而不是通过 UI。

最佳实践

配置 Paideia LMS 时：

• 使用 .env 文件进行本地开发和敏感凭据
• 使用托管环境变量进行生产部署
• **使用 paideia.config.json**用于应该进行版本控制的系统范围设置
• 永远不要将 .env 文件提交到版本控制
• **始终将 paideia.config.json**提交到版本控制（适当删除敏感数据）
• **仅在沙盒模式中使用 seed.json**进行开发和测试
• 将敏感值（密码、API 密钥）保存在环境变量中，而不是配置文件中