全部设置
所有设置都是 deploy/selfhost/.env 里的环境变量。
把设置写在 deploy/selfhost/.env 里，再运行 docker compose up -d。compose 文件会把它传给容器，并设置下面标为 compose 的默认值。带注释的完整列表见
deploy/.env.example；以 apps/api/src/semestra/core/config.py 为准。
Compose 文件
这些变量由 docker-compose.yml 自己读取。
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_VERSION | latest | 镜像版本，例如 1.2.0（见镜像） |
SEMESTRA_IMAGE_VARIANT | -local | 留空则使用不带本机 OCR 与 embedding 的镜像 |
SEMESTRA_PUBLIC_URL | http://localhost:8000 | 用户打开的地址。用于邮件和日历链接；https:// 时 cookie 带 Secure |
SEMESTRA_PORT | 8000 | 宿主机端口 |
SEMESTRA_BIND | 0.0.0.0 | 宿主机网卡。放在反向代理后面时用 127.0.0.1 |
SEMESTRA_DOMAIN | （空） | 内置 Caddy 使用的域名（见有域名的服务器） |
COMPOSE_PROFILES | （空） | https 加入内置 Caddy，ai-local 加入内置 Ollama |
账户与登录
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_SESSION_TTL_DAYS | 30 | 网页会话有效期 |
SEMESTRA_ACCESS_TOKEN_TTL_SECONDS | 900 | 原生客户端访问令牌有效期 |
SEMESTRA_REFRESH_TOKEN_TTL_DAYS | 60 | 原生客户端刷新令牌有效期 |
SEMESTRA_NOTIFY_NEW_SIGN_IN | false | 有新会话登录时给用户发邮件 |
SEMESTRA_GOOGLE_CLIENT_ID | （空） | Google 登录。为空时隐藏 Google 按钮 |
SEMESTRA_TRUSTED_PROXY_HOPS | 0 | API 前面的反向代理层数；客户端 IP 从 X-Forwarded-For 右数这么多层读取 |
SEMESTRA_COOKIE_SECURE | （未设置） | 未设置时，公开地址是 https 就使用 Secure cookie |
邮件设置见邮件。
存储与文件
| 变量 | 默认值（自部署） | 含义 |
|---|---|---|
SEMESTRA_USER_STORAGE_QUOTA_BYTES | 0 compose | 每个用户的存储空间；0 表示不限 |
SEMESTRA_FILES_MAX_UPLOAD_BYTES | 26214400（25 MB） | 单个上传文件的上限 |
SEMESTRA_FILES_PARSE_TIMEOUT_SECONDS | 300 | 解析一个文件的最长时间 |
SEMESTRA_FILES_PARSE_MEMORY_BYTES | 2147483648（2 GB） | 解析进程的内存上限 |
网络
| 变量 | 默认值（自部署） | 含义 |
|---|---|---|
SEMESTRA_ALLOW_PRIVATE_EGRESS | true compose | 允许服务器访问内网和回环地址：局域网里的 Ollama、学校自建的 Canvas、纯 http 的 Canvas。compose 文件之外默认是 false |
设为 false 时，访问用户填写的主机如果解析到内网、回环或链路本地地址，会被拒绝：AI 接口地址返回 common.egress_blocked，Canvas
地址返回 lms.blocked_address。Canvas 返回的每个重定向目标也要通过同样的检查。
Canvas
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_LMS_CANVAS_SIGN_IN | false | Canvas 学校账号登录 |
AI
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_INSTANCE_AI_KIND | （空） | 全实例服务商的类型 |
SEMESTRA_INSTANCE_AI_BASE_URL | （空） | 它的接口地址 |
SEMESTRA_INSTANCE_AI_CHAT_MODEL | （空） | 用于对话、读取文档和生成标题的模型 |
SEMESTRA_INSTANCE_AI_EMBEDDING_MODEL | （空） | 用于搜索的向量模型 |
SEMESTRA_INSTANCE_AI_API_KEY | （空） | 它的密钥，Ollama 可不填 |
SEMESTRA_INSTANCE_AI_MAX_CONCURRENCY | 0 | 同时发给它的请求数上限（0：不限）；配置较低的 Ollama 服务器可设为 1 |
SEMESTRA_AI_WARM_UP | true | 启动后在后台预先加载 AI 相关库 |
见全实例服务商。
本机 OCR
只有默认镜像带这个功能，见镜像。
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_LOCAL_OCR | -local 镜像里为 true | 在服务器上识别扫描页 |
SEMESTRA_LOCAL_OCR_MODEL | PP-OCRv6_medium | 默认模型：PP-OCRv6_tiny、_small、_medium、PP-OCRv5_mobile、PP-OCRv5_server |
SEMESTRA_LOCAL_OCR_PAGE_TIMEOUT_SECONDS | 60 | 每页允许的时间（另加两分钟加载模型）；CPU 很慢时调大 |
本机 embedding
只有默认镜像带这个功能，见镜像。
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_LOCAL_EMBEDDING | -local 镜像里为 true | 在服务器上计算搜索用的向量 |
SEMESTRA_LOCAL_EMBEDDING_MODEL | multilingual-e5-small | 默认模型（预设名或 Hugging Face 模型名） |
SEMESTRA_LOCAL_EMBEDDING_CUSTOM | true | 允许用户添加 Hugging Face 模型；多人共用的服务器可关掉以节省磁盘 |
SEMESTRA_LOCAL_EMBEDDING_MAX_GB | 3 | 用户可添加的模型大小上限 |
SEMESTRA_LOCAL_EMBEDDING_THREADS | 0 | CPU 线程数（0：一半核心） |
SEMESTRA_LOCAL_EMBEDDING_IDLE_SECONDS | 600 | 这么久没用就卸载模型 |
SEMESTRA_LOCAL_EMBEDDING_MAX_LOADED | 2 | 同时保留加载的模型数（每个各占一份内存） |
后台任务与备份
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_JOB_CONCURRENCY | 2 | 进程内后台任务的并发数 |
SEMESTRA_JOB_BULK_CONCURRENCY | 1 | 其中最多几个用于重建搜索向量、下载模型；至少留一个给导入和新文件 |
SEMESTRA_BACKUP_DIR | （空） | 设置后每天自动备份到这个目录 |
SEMESTRA_BACKUP_KEEP | 7 | 保留的数据库快照数 |
密钥与日志
| 变量 | 默认值 | 含义 |
|---|---|---|
SEMESTRA_SECRET_KEY | 自动生成 | 签发会话和令牌 |
SEMESTRA_ENCRYPTION_KEY | 自动生成 | 加密已保存的服务商密钥和 Canvas 令牌的 Fernet 密钥 |
SEMESTRA_LOG_LEVEL | INFO | 日志级别 |
SEMESTRA_SENTRY_DSN | （空） | 把错误报告给 Sentry；为空则关闭 |
只有在 SEMESTRA_AUTO_SECRETS=true 时容器才会生成密钥，compose 文件已经设置了它。签名通知用的密钥由 SEMESTRA_SECRET_KEY 派生；更换后，各浏览器会在下次打开 Semestra 时重新订阅。通知需要 HTTPS（或 localhost），服务器也要能通过 HTTPS 访问浏览器的推送服务。SEMESTRA_SKIP_MIGRATIONS=true
会在启动时跳过迁移。