Skip to content

配置项参考 ​

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

加载机制

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

基础配置 ​

变量类型默认值说明
PORTnumber9001HTTP 服务端口,提供 REST API 与静态前端
WS_PORTnumber10001WebSocket 服务端口,用于实时通讯
HTTPSbooleanfalse是否启用 HTTPS 模式(影响 cookie secure 标记)
HTTPS_PORTnumber9443HTTPS 服务端口,由 PM2 进程 classintra-https(src/app-https.js,WS_MIRROR_MODE=true 的 9001 镜像实例)监听。不再默认 443,要占 443 须显式设 HTTPS_PORT=443
CORS_ORIGINSstring(空)允许跨域的前端域名,逗号分隔。生产环境建议显式指定

HTTPS 与 CORS

公网部署必须:

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

认证配置 ​

v1.4 起 JWT 一律 RS256 签发:私钥来源优先取 JWT_PRIVATE_KEY(PEM 文本或路径),留空则使用默认位置 server/keys/jwt-private.pem,首次启动自动生成 RSA-2048 密钥对(公钥 jwt-public.pem 落同目录)。私钥不出本机;其他服务(如 Cluss)需要验 CI token 时,把 server/keys/jwt-public.pem 交给对方即可。

变量类型默认值说明
JWT_PRIVATE_KEYstring(空)RS256 签发私钥,PEM 文本或文件路径。留空时用 server/keys/jwt-private.pem(不存在则首次启动自动生成 RSA-2048 密钥对)
JWT_PUBLIC_KEYstring(空)RS256 公钥(可选),供其他服务验签;一般直接分发 server/keys/jwt-public.pem 文件
JWT_SECRETstring(空)HS256 共享密钥,仅过渡期验旧 token 与兜底;私钥不可用且此值为空时拒绝签发 token
JWT_EXPIRES_INstring7dJWT 过期时间,支持 1h / 7d / 30d 等
ADMIN_USER_IDSstring(空)班管 ID 列表,格式 YYCC00,逗号分隔,如 250100,250200
DEV_PASSWORDstring(空)开发者测试账号密码,设置后创建 ID=999999 的开发者账号。生产环境必须留空

班管 ID 格式

YYCC00 含义:

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

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

RS256 私钥保护

  • 默认密钥对落盘 server/keys/jwt-private.pem(权限 600)与 jwt-public.pem,首次启动自动生成,无需手工配置
  • 私钥不出本机、不可提交 Git;server/keys/ 属敏感目录,备份时加密保存
  • 验签优先走非对称算法白名单(RS256/RS384/RS512/ES256/ES384/ES512,显式指定防降级攻击),失败再退 HS256(JWT_SECRET)验旧 token,旧 token 平滑过渡不登出

天气配置 ​

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

变量类型默认值说明
QWEATHER_KEYstring(空)和风天气 API Key(基础鉴权)
QWEATHER_LOCATIONstring(空)默认城市坐标,格式 经度,纬度,如 116.41,39.92
QWEATHER_API_HOSTstringdevapi.qweather.comAPI 主机,免费版用 devapi.qweather.com,商业版用 api.qweather.com
QWEATHER_KIDstring(空)JWT 鉴权 Credential ID(可选)
QWEATHER_SUBstring(空)JWT 鉴权 Subject(项目 ID)
QWEATHER_PRIVATE_KEYstring(空)JWT 鉴权 EdDSA 私钥(PEM 格式)

鉴权方式选择

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

私钥保护

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

数据存储配置 ​

变量类型默认值说明
DB_PATHstring./database/classintra.dbSQLite 数据库文件路径(相对于 server/)
RESOURCES_DIRstring../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_SERVERSstring(空)对端服务器列表,逗号分隔,格式 host:port
RELAY_SECRETstring(空)中继共享密钥,所有节点必须一致
RELAY_SERVER_IDstring(空)本节点唯一标识,如 server-a / class-1
RELAY_PORTnumber10011本节点中继监听端口
COHORTstring(空)届数标识,逗号分隔,同届才同步;留空自动从 ADMIN_USER_IDS 推断

RELAY_SECRET 与 JWT 无关

RELAY_SECRET 用于跨班 Relay 消息同步、POST /api/auth/relay-verify 跨班联登校验,以及 Cluss 联动桥鉴权(请求头 X-Bridge-Secret 与其同值),与 JWT 签名(RS256)无关。

配置示例

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

插件与集成 ​

市场源与安装限制 ​

班级默认从官方 Gitee / GitHub / 本地目录安装市场应用。需要接第三方自建市场时用 MARKET_SOURCES:

变量类型默认值说明
MARKET_SOURCESstring(空)自定义市场源。JSON 数组 [{"id","label","base"}],或简写 id|label|base 逗号分隔
MARKET_LOCAL_DIRstring<项目根>/../market内置 local 源指向的目录
MARKET_MAX_FILESnumber300单应用文件数上限
MARKET_MAX_FILE_MBnumber60单文件大小上限(MB)
MARKET_MAX_TOTAL_MBnumber80单应用总大小上限(MB)
MARKET_RESTRICTED_CAPABILITIESstring(空)逗号分隔的能力名,声明即拒装(如 device.camera,data.http)
MARKET_SIGNING_PUBLIC_KEYstring(空)ed25519 公钥(PEM 文本或文件路径),启用后官方源目录必须验签

自定义源也能在管理端加

市场页 →「源」→ 填写 id / 显示名 / index.json 所在目录即可,无需改 .env。 环境变量适合部署时固化;管理端添加适合临时接入。内置三源与环境变量源不可在管理端删除。

兼容模式(web-proxy 插件) ​

web-proxy 插件(静态反代 9101 + 老内核兼容渲染)随主程序自动启动。自动启动开关在 ecosystem.config.js 中硬编码(默认 '0',即关闭),也可通过插件自身配置在 plugins/web-proxy/backend/routes.js:31 中设默认值 '1';如需关闭自启,在 ecosystem.config.js 中按需调整即可。

云盘 bot 转运(Cluss 集成) ​

AstrBot 下载的媒体文件被学生转存云盘时,改由 bot 硬链接转运(同盘零占用;转运不可达时自动回退本地复制):

变量类型默认值说明
BOT_TRANSFER_URLstringhttp://127.0.0.1:6200AstrBot 插件转运接口地址
BOT_TRANSFER_TOKENstring(空)转运接口鉴权 token,插件未开鉴权时留空
BOT_TRANSFER_TIMEOUT_MSnumber10000转运请求超时(毫秒)

同步配置 ​

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

变量类型默认值说明
SYNCTHING_HOSTstringlocalhostSyncthing REST API 主机
SYNCTHING_PORTnumber8384Syncthing REST API 端口
SYNCTHING_API_KEYstring(空)Syncthing API Key

何时启用

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

VPN 配置 ​

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

变量类型默认值说明
TAILSCALE_ENABLEDbooleanfalse是否启用 Tailscale 集成
TAILSCALE_RELAY_IPstring(空)对端服务器的 Tailscale IP(如 100.64.0.1)
TAILSCALE_STATUS_CMDstringtailscale status --json检查节点状态的命令

Tailscale 与 Relay 配合

启用 Tailscale 后,RELAY_SERVERS 改为对端的 Tailscale IP:

bash
TAILSCALE_ENABLED=true
RELAY_SERVERS=100.64.0.2:10011

日志配置 ​

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

详细日志性能

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

配置示例 ​

单班级最小配置 ​

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

# JWT 默认 RS256:私钥首次启动自动生成于 server/keys/(可选 JWT_PRIVATE_KEY)
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 默认 RS256,私钥首次启动自动生成于 server/keys/;可选显式指定
# JWT_PRIVATE_KEY=
JWT_EXPIRES_IN=7d

ADMIN_USER_IDS=250100
COHORT=25

# 天气
QWEATHER_KEY=<your-qweather-key>
QWEATHER_LOCATION=116.41,39.92

# 安全
HTTPS=true
HTTPS_PORT=9443
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_EXPIRES_IN=7d
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 默认 RS256,各机私钥独立自动生成,互不影响
# 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 可查看运行中的部分配置(端口、版本)。完整配置需登录后访问管理后台查看。

下一步 ​

基于 MIT 协议 开源 · 加入 QQ 群【ClassIntra】
本项目 LOGO 来源于公共素材库,仅用于非商业教育目的,权利归其各自所有者;与其他项目 LOGO 的相似纯属巧合。
The logo is sourced from a public domain asset library and is used for non-commercial, educational purposes only.