环境变量
本文集中说明 Docker Compose、Django 后端、Celery、人脸识别服务以及镜像构建阶段使用的环境变量。
项目根目录的 .env 文件有两类用途：
- Docker Compose 会用它展开
docker-compose.yml/docker-compose.prod.yml中的${...}。 - 后端、Celery 和前端开发容器通过
env_file: .env读取运行时变量。
WARNING
不要提交真实 .env 文件。生产环境中的密码、密钥、对象存储凭据、微信密钥和 SM2 私钥应使用强随机值，并尽量由密钥管理系统托管。
最小配置
开发环境至少需要：
text
POSTGRES_PASSWORD=password
DJANGO_DEBUG=true
SM2_PUBLIC_KEY=your_sm2_public_key
SM2_PRIVATE_KEY=your_sm2_private_key生产环境至少需要：
text
POSTGRES_DB=myucspace
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change_me_to_a_strong_password
POSTGRES_HOST=db
POSTGRES_PORT=5432
DJANGO_DEBUG=false
DJANGO_SECRET_KEY=change_me_to_a_long_random_secret
DJANGO_ALLOWED_HOSTS=example.com,localhost,127.0.0.1
CSRF_DOMAINS=https://example.com
CORS_ALLOWED_ORIGINS=https://example.com
SM2_PUBLIC_KEY=your_sm2_public_key
SM2_PRIVATE_KEY=your_sm2_private_key
REDIS_URL=redis://redis:6379/2
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/1TIP
当前项目使用 PostgreSQL。旧文档中的 MYSQL_* 变量已不适用于当前 Compose 和 Django 配置。
构建阶段变量
这些变量影响 Docker 镜像构建，已在 Compose 的 build.args 中接入。默认使用官方源；国内服务器可在 .env 中覆盖。
| 变量 | 默认值 | 说明 |
|---|---|---|
DEBIAN_MIRROR_HOST | 空 | 可选 apt 源主机。为空时使用基础镜像默认 Debian 源；例如 mirrors.tuna.tsinghua.edu.cn。 |
PYTHON_PACKAGE_INDEX_URL | https://pypi.org/simple | pip 安装 uv 以及 uv pip install 解析依赖时使用的 Python 包索引。 |
PYTHON_PACKAGE_TRUSTED_HOST | 空 | 可选 trusted/insecure host。传入后会映射到 pip 的 PIP_TRUSTED_HOST 和 uv 的 UV_INSECURE_HOST。 |
国内构建示例：
text
DEBIAN_MIRROR_HOST=mirrors.tuna.tsinghua.edu.cn
PYTHON_PACKAGE_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
PYTHON_PACKAGE_TRUSTED_HOST=mirrors.tuna.tsinghua.edu.cnINFO
Dockerfile 内部会把 PYTHON_PACKAGE_INDEX_URL 映射为 PIP_INDEX_URL 和 UV_DEFAULT_INDEX。通常只需要填写上表中的三个变量，不要直接在 .env 中维护 pip/uv 的内部变量。
数据库
| 变量 | 默认值 | 说明 |
|---|---|---|
POSTGRES_DB | postgres | Django 连接的数据库名；Postgres 容器也会使用该值初始化数据库。 |
POSTGRES_USER | postgres | 数据库用户名。 |
POSTGRES_PASSWORD | password | 数据库密码。官方 Postgres 镜像要求设置该变量；生产环境必须替换为强密码。 |
POSTGRES_HOST | db | Django 连接数据库的主机名；Compose 内通常保持为 db。 |
POSTGRES_PORT | 5432 | Django 连接数据库的端口。 |
Django 核心
| 变量 | 默认值 | 说明 |
|---|---|---|
DJANGO_DEBUG | false | 是否开启调试模式。开发环境可设为 true；生产环境必须为 false。 |
DJANGO_SECRET_KEY | 无 | Django 密钥。DJANGO_DEBUG=false 时必须设置；开发调试模式缺省时会使用占位密钥。 |
DJANGO_ALLOWED_HOSTS | localhost,127.0.0.1,backend,10.0.2.2 | 允许访问后端的 Host 列表，英文逗号分隔。生产设置模块会覆盖为“未设置即空列表”。 |
CSRF_DOMAINS | 空 | 生产环境 CSRF 可信来源，必须包含协议，例如 https://example.com，多个值用英文逗号分隔。 |
CORS_ALLOWED_ORIGINS | http://localhost:5173,http://localhost:3000,http://localhost | 允许携带 Cookie 跨域访问 API 的前端 Origin，英文逗号分隔。 |
LOGIN_THROTTLE_RATE | 5/minute | 登录接口限流频率。 |
SM2 登录加密
| 变量 | 默认值 | 说明 |
|---|---|---|
SM2_PUBLIC_KEY | 无 | 前端加密登录密码使用的公钥。 |
SM2_PRIVATE_KEY | 无 | 后端解密登录密码使用的私钥。缺少时后端可启动，但登录流程不可用。 |
WebAuthn 与 TOTP
| 变量 | 默认值 | 说明 |
|---|---|---|
TOTP_ISSUER_NAME | MyUCSpace | TOTP 认证器中显示的发行方名称。 |
WEBAUTHN_RP_ID | 空 | WebAuthn Relying Party ID，生产环境通常为域名。 |
WEBAUTHN_RP_NAME | MyUCSpace | WebAuthn Relying Party 名称。 |
WEBAUTHN_ORIGIN | http://localhost:8000 | WebAuthn Origin，生产环境应为 HTTPS 域名。 |
文件存储
| 变量 | 默认值 | 说明 |
|---|---|---|
FILE_STORAGE_BACKEND | local | 文件存储后端，支持 local / s3。 |
LOCAL_UPLOAD_DIR | /data/uploads | 本地上传文件目录。 |
LOCAL_UPLOAD_URL_PREFIX | /media/uploads/ | 本地上传文件 URL 前缀。 |
S3_ACCESS_KEY_ID | 无 | S3 兼容对象存储 Access Key。 |
S3_SECRET_ACCESS_KEY | 无 | S3 兼容对象存储 Secret Key。 |
S3_BUCKET_NAME | 无 | S3 Bucket 名称。 |
S3_REGION | 无 | S3 区域。 |
S3_ENDPOINT_URL | 无 | S3 兼容服务 Endpoint。 |
S3_BASE_URL | 无 | 对象访问基础 URL。S3 模式下 S3_BASE_URL 或 S3_ENDPOINT_URL 至少需要一个可用于生成访问 URL。 |
微信小程序与班牌
| 变量 | 默认值 | 说明 |
|---|---|---|
WECHAT_APP_ID | 空 | 微信小程序 App ID。 |
WECHAT_APP_SECRET | 空 | 微信小程序 App Secret。 |
SIGNAGE_BASE_URL | http://10.0.2.2:8000/api/v1/ | Android 班牌访问后端 API 的基础 URL。 |
SIGNAGE_APK_DIR | /data/signageapk/ | 班牌 APK 文件目录。 |
SIGNAGE_APK_URL_PREFIX | /media/signageapk/ | 班牌 APK 下载 URL 前缀。 |
Redis 与 Celery
| 变量 | 默认值 | 说明 |
|---|---|---|
REDIS_URL | redis://localhost:6379/2 | Django 缓存使用的 Redis URL。Compose 环境中通常设为 redis://redis:6379/2。 |
CELERY_BROKER_URL | redis://localhost:6379/0 | Celery 消息代理 URL。Compose 环境中通常设为 redis://redis:6379/0。 |
CELERY_RESULT_BACKEND | redis://localhost:6379/1 | Celery 结果后端 URL。Compose 环境中通常设为 redis://redis:6379/1。 |
人脸识别
| 变量 | 默认值 | 说明 |
|---|---|---|
FACE_SERVICE_URL | http://face-service:9000 | Django 调用人脸识别服务的 URL。当前核心后端和 Android 班牌流程不强依赖该服务。 |
FACE_MATCH_THRESHOLD | 0.45 | 后端人脸匹配阈值。 |
INSIGHTFACE_HOME | /models/insightface | face-service 加载 InsightFace 模型的根目录；生产 Compose 固定为 /app/insightface。 |
CUDA_VISIBLE_DEVICES | 未设置 | face-service 运行设备选择；生产 Compose 当前设为 -1，即禁用 CUDA。 |
PYTHONUNBUFFERED | 未设置 | Python 日志不缓冲输出；生产 face-service 设为 1。 |
PYTHONDONTWRITEBYTECODE | 未设置 | 禁止写入 .pyc；生产 face-service 设为 1。 |
示例：生产 .env
text
DEBIAN_MIRROR_HOST=mirrors.tuna.tsinghua.edu.cn
PYTHON_PACKAGE_INDEX_URL=https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
PYTHON_PACKAGE_TRUSTED_HOST=mirrors.tuna.tsinghua.edu.cn
POSTGRES_DB=myucspace
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change_me_to_a_strong_password
POSTGRES_HOST=db
POSTGRES_PORT=5432
DJANGO_DEBUG=false
DJANGO_SECRET_KEY=change_me_to_a_long_random_secret
DJANGO_ALLOWED_HOSTS=example.com,localhost,127.0.0.1
CSRF_DOMAINS=https://example.com
CORS_ALLOWED_ORIGINS=https://example.com
SM2_PUBLIC_KEY=your_sm2_public_key
SM2_PRIVATE_KEY=your_sm2_private_key
REDIS_URL=redis://redis:6379/2
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/1
WECHAT_APP_ID=your_wechat_app_id
WECHAT_APP_SECRET=your_wechat_app_secret