配置项参考

ClassIntra 通过 server/.env 文件配置全部运行参数。本页面列出所有环境变量，按功能分类，便于查阅与排查。

加载机制

环境变量由 server/src/config/index.js 在服务启动时读取，PM2 模式下由 ecosystem.config.js 自动注入。修改后需重启服务（pm2 restart classintra-server）生效。

基础配置

变量	类型	默认值	说明
`PORT`	number	`9001`	HTTP 服务端口，提供 REST API 与静态前端
`WS_PORT`	number	`10001`	WebSocket 服务端口，用于实时通讯
`HTTPS`	boolean	`false`	是否启用 HTTPS 模式（影响 cookie secure 标记）
`CORS_ORIGINS`	string	（空）	允许跨域的前端域名，逗号分隔。生产环境建议显式指定

HTTPS 与 CORS

公网部署必须：

HTTPS=true 启用 secure cookie
CORS_ORIGINS=https://your.domain.com 限制跨域

认证配置

变量	类型	默认值	说明
`JWT_SECRET`	string	必填	JWT 签名密钥，≥32 字符随机串，未设置则服务拒绝启动
`JWT_EXPIRES_IN`	string	`7d`	JWT 过期时间，支持 `1h` / `7d` / `30d` 等
`ADMIN_USER_IDS`	string	（空）	班管 ID 列表，格式 `YYCC00`，逗号分隔，如 `250100,250200`
`DEV_PASSWORD`	string	（空）	开发者测试账号密码，设置后创建 ID=`999999` 的开发者账号。生产环境必须留空

班管 ID 格式

YYCC00 含义：

YY —— 届数（毕业年后两位，如 25 = 2025 届）
CC —— 班级编号（如 08 = 8 班）
00 —— 固定后缀（标识班管身份）

班管不预创建账号，真实用户通过预注册名单注册后，系统匹配 ADMIN_USER_IDS 自动授予管理员权限。

JWT_SECRET 安全

不可使用模板默认值 change-this-to-a-secure-random-string-at-least-32-chars
生成随机密钥：node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
密钥泄露后所有 JWT 失效，需重新签发
生产环境建议每 90 天轮换

AI 配置

v1.3 起，AI 聊天采用模型注册表（ai_models 表）驱动，支持接入任意 OpenAI 兼容 API：GLM、Qwen、Kimi、DeepSeek、自建网关、第三方中转站均可，接入数量与来源不限。模型的新增、编辑、启停（控制用户可见性）、设默认、连接测试全部在 AI 应用内「模型管理」面板完成（系统管理员与班管可见；新建时可从厂商模板一键填充）。

配置分层

层	入口	管什么
运行时	AI 应用右上角「模型管理」（管理员）	模型接入、启停、默认模型、能力开关（思考/联网）
基础设施	`server/.env`（可用 ClassIntraOps 密钥页配置）	内置模型（`default` / `deepseek`）留空字段的兜底值，Tavily 搜索密钥

优先级

模型注册表中内置行的 api_url / api_key / model 留空时回退到环境变量；管理面板填写的值优先于 .env。自定义模型必须在面板中完整填写地址与密钥。

内置模型兜底（环境变量）

AI_* 与 DEEPSEEK_* 仅作为模型注册表两条内置种子行的兜底值：

变量	类型	默认值	说明
`AI_API_KEY`	string	（空）	内置 `default` 模型的 API Key
`AI_API_URL`	string	（空）	OpenAI Chat Completions 兼容接口地址
`AI_MODEL`	string	`gpt-3.5-turbo`	请求体 `model` 参数兜底值
`AI_AVAILABLE_MODELS`	string	—	历史遗留（v1.2 前的子模型切换），仅作初始化参考
`DEEPSEEK_API_KEY`	string	（空）	内置 `deepseek` 模型的 API Key
`DEEPSEEK_API_URL`	string	`https://api.deepseek.com/chat/completions`	DeepSeek 接口地址
`DEEPSEEK_MODEL`	string	`deepseek-chat`	默认模型

思考模式参数风格

支持「深度思考」的模型需在管理面板选择思考参数风格：DeepSeek / GLM 风格（注入 thinking: {type: enabled}）或 OpenAI 标准（不注入专用参数）。选错风格可能导致上游返回 422。

天气配置

ClassIntra 集成和风天气服务，支持 API Key 与 JWT 两种鉴权方式。

变量	类型	默认值	说明
`QWEATHER_KEY`	string	（空）	和风天气 API Key（基础鉴权）
`QWEATHER_LOCATION`	string	（空）	默认城市坐标，格式 `经度,纬度`，如 `116.41,39.92`
`QWEATHER_API_HOST`	string	`devapi.qweather.com`	API 主机，免费版用 `devapi.qweather.com`，商业版用 `api.qweather.com`
`QWEATHER_KID`	string	（空）	JWT 鉴权 Credential ID（可选）
`QWEATHER_SUB`	string	（空）	JWT 鉴权 Subject（项目 ID）
`QWEATHER_PRIVATE_KEY`	string	（空）	JWT 鉴权 EdDSA 私钥（PEM 格式）

鉴权方式选择

API Key：免费版默认，设置 QWEATHER_KEY 即可
JWT 鉴权：商业版推荐，设置 QWEATHER_KID + QWEATHER_SUB + QWEATHER_PRIVATE_KEY，安全性更高
两种方式可共存，优先使用 JWT

私钥保护

QWEATHER_PRIVATE_KEY 是敏感信息，文件权限设为 600，不可提交到 Git。server/.env 已在 .gitignore 中。

搜索配置

AI 聊天的联网搜索功能基于 Tavily。模型注册表中勾选了「联网搜索」能力的模型，对话时会自动调用搜索工具。

变量	类型	默认值	说明
`TAVILY_API_KEY`	string	（空）	Tavily API Key
`TAVILY_API_URL`	string	`https://api.tavily.com/search`	Tavily 搜索接口地址

未配置时的行为

未设置 TAVILY_API_KEY 时，即使模型勾选了联网搜索能力，实际请求也不会携带搜索工具，普通对话不受影响。

数据存储配置

变量	类型	默认值	说明
`DB_PATH`	string	`./database/classintra.db`	SQLite 数据库文件路径（相对于 `server/`）
`RESOURCES_DIR`	string	`../Resources`	静态资源根目录（相对 `server/`），存放照片、云盘、壁纸等

数据库路径

默认存储在 server/database/classintra.db
启用 WAL 模式提升并发读写性能（classintra.db-wal 与 classintra.db-shm 是 WAL 附属文件，备份时一起复制）
路径可改为绝对路径，如 /var/lib/classintra/db.sqlite

备份完整性

SQLite 备份必须包含以下三个文件：

classintra.db —— 主数据库
classintra.db-wal —— WAL 日志
classintra.db-shm —— 共享内存索引

缺失任一文件都可能导致数据不一致。

中继配置

跨服务器中继（Relay）用于多班级、多机部署场景的消息同步。

变量	类型	默认值	说明
`RELAY_SERVERS`	string	（空）	对端服务器列表，逗号分隔，格式 `host:port`
`RELAY_SECRET`	string	（空）	中继共享密钥，所有节点必须一致
`RELAY_SERVER_ID`	string	（空）	本节点唯一标识，如 `server-a` / `class-1`
`RELAY_PORT`	number	`10011`	本节点中继监听端口
`COHORT`	string	（空）	届数标识，逗号分隔，同届才同步；留空自动从 `ADMIN_USER_IDS` 推断

配置示例

bash

# 服务器 A
RELAY_SERVER_ID=server-a
RELAY_SERVERS=192.168.1.101:10011
RELAY_SECRET=<32 字符随机串>
RELAY_PORT=10011
COHORT=25

# 服务器 B
RELAY_SERVER_ID=server-b
RELAY_SERVERS=192.168.1.100:10011
RELAY_SECRET=<同 A 的密钥>
RELAY_PORT=10011
COHORT=25

同步配置

Syncthing 用于跨服务器的资源文件同步（云盘、照片等），非中继消息。

变量	类型	默认值	说明
`SYNCTHING_HOST`	string	`localhost`	Syncthing REST API 主机
`SYNCTHING_PORT`	number	`8384`	Syncthing REST API 端口
`SYNCTHING_API_KEY`	string	（空）	Syncthing API Key

何时启用

仅在多机部署且需要共享大文件（如云盘资源）时启用 Syncthing。单机部署无需配置。Syncthing 服务需独立安装，详见 Syncthing 文档。

VPN 配置

Tailscale 用于跨校区组网，无需开放公网端口。

变量	类型	默认值	说明
`TAILSCALE_ENABLED`	boolean	`false`	是否启用 Tailscale 集成
`TAILSCALE_RELAY_IP`	string	（空）	对端服务器的 Tailscale IP（如 `100.64.0.1`）
`TAILSCALE_STATUS_CMD`	string	`tailscale status --json`	检查节点状态的命令

Tailscale 与 Relay 配合

启用 Tailscale 后，RELAY_SERVERS 改为对端的 Tailscale IP：

bash

TAILSCALE_ENABLED=true
RELAY_SERVERS=100.64.0.2:10011

日志配置

变量	类型	默认值	说明
`VERBOSE_LOG`	number	`0`	详细日志开关，`0` 关闭 / `1` 启用活动日志记录

详细日志性能

VERBOSE_LOG=1 会记录每个 HTTP 请求、WebSocket 消息、Relay 同步事件，磁盘占用快速增长。仅排查问题时临时启用，排查后立即恢复为 0。

配置示例

单班级最小配置

bash

# server/.env —— 单班最小可用
PORT=9001
WS_PORT=10001

JWT_SECRET=<32 字符随机串>
JWT_EXPIRES_IN=7d

ADMIN_USER_IDS=250100
COHORT=25

DB_PATH=./database/classintra.db
RESOURCES_DIR=../Resources

# HTTPS=false（内网）
# CORS_ORIGINS=（留空，允许所有来源）
VERBOSE_LOG=0

公网生产配置

bash

# server/.env —— 公网部署
PORT=9001
WS_PORT=10001

JWT_SECRET=<32 字符随机串>
JWT_EXPIRES_IN=7d

ADMIN_USER_IDS=250100
COHORT=25

# AI / 天气 / 搜索
AI_API_KEY=<your-key>
AI_API_URL=https://api.openai.com/v1/chat/completions
AI_MODEL=gpt-4o-mini
QWEATHER_KEY=<your-qweather-key>
QWEATHER_LOCATION=116.41,39.92
TAVILY_API_KEY=<your-tavily-key>

# 安全
HTTPS=true
CORS_ORIGINS=https://classintra.example.edu

# 数据存储
DB_PATH=./database/classintra.db
RESOURCES_DIR=../Resources

# 关闭开发者后门
# DEV_PASSWORD=

# 关闭详细日志
VERBOSE_LOG=0

多班级中继配置

bash

# 服务器 A（1 班）
PORT=9001
WS_PORT=10001
JWT_SECRET=<32 字符随机串>
ADMIN_USER_IDS=250100
COHORT=25
DB_PATH=./database/classintra.db

RELAY_SERVER_ID=class-1
RELAY_SERVERS=192.168.1.101:10011   # 2 班
RELAY_SECRET=<共享密钥>
RELAY_PORT=10011

# 服务器 B（2 班）
# PORT=9001
# WS_PORT=10001
# JWT_SECRET=<同 A，或不同>
# ADMIN_USER_IDS=250200
# COHORT=25
# RELAY_SERVER_ID=class-2
# RELAY_SERVERS=192.168.1.100:10011   # 1 班
# RELAY_SECRET=<同 A>
# RELAY_PORT=10011

配置同步

所有中继节点的 RELAY_SECRET 必须完全一致，否则握手失败。建议使用密码管理器分发，避免人工输入错误。

环境变量优先级

ClassIntra 配置加载顺序（后者覆盖前者）：

1. server/.env 文件
       ↓
2. 系统环境变量（如 export PORT=9002）
       ↓
3. PM2 ecosystem.config.js 中的 env 字段
       ↓
4. 命令行参数（极少用）

调试当前生效值

访问 GET /api/system/health 可查看运行中的部分配置（端口、版本）。完整配置需登录后访问管理后台查看。

下一步

生产部署 - 完整部署流程
教育场景 - 班级部署实战
监控运维 - 日志与故障排查
API 参考 - 服务端 API 文档

配置项参考 ​

基础配置 ​

认证配置 ​

AI 配置 ​

配置分层 ​

内置模型兜底（环境变量） ​

天气配置 ​

搜索配置 ​

数据存储配置 ​

中继配置 ​

同步配置 ​

VPN 配置 ​

日志配置 ​

配置示例 ​

单班级最小配置 ​

公网生产配置 ​

多班级中继配置 ​

环境变量优先级 ​

下一步 ​

配置项参考

基础配置

认证配置

AI 配置

配置分层

内置模型兜底（环境变量）

天气配置

搜索配置

数据存储配置

中继配置

同步配置

VPN 配置

日志配置

配置示例

单班级最小配置

公网生产配置

多班级中继配置

环境变量优先级

下一步