环境变量
配置分层（约定）
- 环境变量唯一事实源为各项目
.env。
- 后端实际读取逻辑以
Beancount-Trans-Backend/project/settings/settings.py 为准；下表用于按场景检索变量。
字段说明：
- 必填级别：
必填 / 条件必填 / 可选
- 模板：
deploy（仅主仓自托管模板出现）/ dev（仅后端开发模板出现）/ both（两套模板均出现，或文档约定两处需同步关注）
核心与网络
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
DJANGO_SETTINGS_MODULE | 可选 | project.settings.settings | Django 设置模块 | both |
DJANGO_SECRET_KEY | 必填 | 示例占位 | Django 密钥，生产必须替换 | both |
DJANGO_DEBUG | 可选 | True | 调试模式 | both |
DJANGO_ALLOWED_HOSTS | 条件必填 | 注释示例 | DEBUG=False 时配置允许域名 | both |
CSRF_TRUSTED_ORIGINS | 条件必填 | 注释示例 | DEBUG=False 时配置 CSRF 来源 | both |
CORS_ALLOWED_ORIGINS | 条件必填 | 注释示例或本地示例 | 跨域来源列表（逗号分隔） | both |
PostgreSQL
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
TRANS_POSTGRESQL_DATABASE | 可选 | beancount-trans | 数据库名 | both |
TRANS_POSTGRESQL_USER | 可选 | root | 数据库用户名 | both |
TRANS_POSTGRESQL_PASSWORD | 必填 | root | 数据库密码 | both |
TRANS_POSTGRESQL_HOST | 可选 | beancount-trans-postgres（deploy）/127.0.0.1（dev） | 数据库主机 | both |
TRANS_POSTGRESQL_PORT | 可选 | 5432 | 数据库端口 | both |
Redis
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
TRANS_REDIS_HOST | 可选 | beancount-trans-redis（deploy）/127.0.0.1（dev） | Redis 主机 | both |
TRANS_REDIS_PORT | 可选 | 6379 | Redis 端口 | both |
TRANS_REDIS_PASSWORD | 必填 | root | Redis 密码 | both |
存储（MinIO / OSS / S3）
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
STORAGE_TYPE | 可选 | minio | 存储类型：minio / oss / s3 | both |
MINIO_ENDPOINT | 条件必填 | beancount-trans-minio:9000（deploy）/127.0.0.1:9000（dev） | STORAGE_TYPE=minio 时使用 | both |
MINIO_ACCESS_KEY | 条件必填 | minioadmin | STORAGE_TYPE=minio 时使用 | both |
MINIO_SECRET_KEY | 条件必填 | minioadmin | STORAGE_TYPE=minio 时使用 | both |
MINIO_BUCKET_NAME | 条件必填 | beancount-trans | STORAGE_TYPE=minio 时使用 | both |
MINIO_USE_HTTPS | 可选 | False | MinIO 是否 HTTPS | both |
OSS_ENDPOINT | 条件必填 | oss-cn-hangzhou.aliyuncs.com | STORAGE_TYPE=oss 时使用 | dev |
OSS_ACCESS_KEY_ID | 条件必填 | 空 | STORAGE_TYPE=oss 时使用 | dev |
OSS_ACCESS_KEY_SECRET | 条件必填 | 空 | STORAGE_TYPE=oss 时使用 | dev |
OSS_BUCKET_NAME | 条件必填 | beancount-trans | STORAGE_TYPE=oss 时使用 | dev |
OSS_REGION | 可选 | cn-hangzhou | STORAGE_TYPE=oss 时使用 | dev |
S3_ENDPOINT_URL | 条件必填 | https://s3.amazonaws.com | STORAGE_TYPE=s3 时使用 | dev |
S3_ACCESS_KEY_ID | 条件必填 | 空 | STORAGE_TYPE=s3 时使用 | dev |
S3_SECRET_ACCESS_KEY | 条件必填 | 空 | STORAGE_TYPE=s3 时使用 | dev |
S3_BUCKET_NAME | 条件必填 | beancount-trans | STORAGE_TYPE=s3 时使用 | dev |
S3_REGION | 可选 | us-east-1 | STORAGE_TYPE=s3 时使用 | dev |
S3_USE_SSL | 可选 | True | STORAGE_TYPE=s3 时使用 | dev |
S3_VERIFY_SSL | 可选 | True | STORAGE_TYPE=s3 时使用 | dev |
认证、OAuth、短信、JWT
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
PHONE_BINDING_REQUIRED | 可选 | False（deploy 建议） | 是否强制手机号绑定 | deploy |
SMS_ENABLED | 可选 | False（deploy 建议） | 是否启用短信流程 | deploy |
JWT_ACCESS_TOKEN_HOURS | 可选 | 720（deploy）/72（dev 示例） | Access Token 有效小时 | both |
GITHUB_CLIENT_ID | 可选 | 示例占位 | GitHub OAuth Client ID | dev |
GITHUB_CLIENT_SECRET | 可选 | 示例占位 | GitHub OAuth Client Secret | dev |
GOOGLE_CLIENT_ID | 可选 | 示例占位 | Google OAuth Client ID | dev |
GOOGLE_CLIENT_SECRET | 可选 | 示例占位 | Google OAuth Client Secret | dev |
ALIYUN_SMS_ACCESS_KEY_ID | 可选 | 示例占位 | 阿里云短信 AccessKey ID | dev |
ALIYUN_SMS_ACCESS_KEY_SECRET | 可选 | 示例占位 | 阿里云短信 AccessKey Secret | dev |
ALIYUN_SMS_SIGN_NAME | 可选 | 示例占位 | 短信签名 | dev |
ALIYUN_SMS_TEMPLATE_CODE | 可选 | 示例占位 | 短信模板代码 | dev |
邮箱（完整字段）
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
DEFAULT_FROM_EMAIL | 可选 | 示例占位 | 发件人地址 | both |
EMAIL_BIND_SUBJECT | 可选 | 邮箱绑定验证码 | 邮件主题（绑定场景） | dev |
EMAIL_BACKEND | 可选 | SMTP 或控制台后端 | Django 邮件后端 | both |
EMAIL_HOST | 可选 | smtp.qq.com（示例） | SMTP 主机 | both |
EMAIL_PORT | 可选 | 465（示例） | SMTP 端口 | both |
EMAIL_HOST_USER | 可选 | 示例占位 | SMTP 用户 | both |
EMAIL_HOST_PASSWORD | 可选 | 示例占位 | SMTP 密码/授权码 | both |
EMAIL_USE_SSL | 可选 | true（示例） | SSL 开关 | both |
EMAIL_USE_TLS | 可选 | false（示例） | TLS 开关 | dev |
EMAIL_TIMEOUT | 可选 | 15 | SMTP 超时秒数 | dev |
EMAIL_CODE_EXPIRE_SECONDS | 可选 | 300 | 邮件验证码有效期 | dev |
EMAIL_CODE_RESEND_INTERVAL | 可选 | 60 | 邮件验证码重发间隔 | dev |
Fava / 路由 / 资产路径
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
FAVA_DEPLOY_MODE | 可选 | static（deploy）/见后端默认 | Fava 部署模式 | both |
FAVA_STATIC_USER_MAP | 条件必填 | admin=http://127.0.0.1:5001 | 静态模式用户到 URL 映射 | deploy |
FAVA_IMAGE | 可选 | dhr2333/beancount-trans-assets:latest | Fava 镜像 | both |
TRAEFIK_NETWORK | 可选 | shared-network | 动态模式网络名 | dev |
BASE_URL | 可选 | localhost | 基础域名（回调/路由） | dev |
CERTRESOLVER | 可选 | alicloud-dns | 证书解析器 | dev |
ASSETS_HOST_PATH | 可选 | 示例路径 | 宿主机 Assets 绝对路径 | dev |
Git / Gitea / GitHub Token
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
GITEA_BASE_URL | 可选 | 示例地址 | Gitea 服务地址 | both |
GITEA_ADMIN_TOKEN | 可选 | 空 | 管理员 Token | both |
GITEA_ORG_NAME | 可选 | beancount-trans | Gitea 组织名 | both |
GITEA_WEBHOOK_SECRET | 可选 | 空 | 平台托管仓库 Webhook 验签密钥 | both |
GITEA_SSH_BASE | 可选 | ssh://git@gitea.dhr2333.cn:30022 | SSH 克隆基址（无尾斜杠） | dev |
GIT_WEBHOOK_STRICT | 可选 | False | Webhook 严格校验开关 | dev |
GIT_REPO_SIZE_LIMIT | 可选 | 20971520 | 仓库大小限制（字节） | both |
GITHUB_TOKEN | 可选 | 空 | GitHub PAT（模板仓库访问） | dev |
HTTP API
| 路径 | 说明 |
|---|
/api/docs/ | ReDoc 交互文档（经前端 Nginx 时与 Web 同源，例如 http://<主机>:38001/api/docs/） |
/api/schema/ | OpenAPI 3 Schema（JSON） |
/api/_allauth/ | allauth headless 接口根路径 |
认证请求头：Authorization: Bearer <access_token>。Access Token 有效期见 .env 中 JWT_ACCESS_TOKEN_HOURS（自托管以主仓模板为准）。
线上示例：Beancount-Trans API（ReDoc）
| 术语 | 定义 |
|---|
| 账本 | 以 Beancount 文本（.bean）承载的复式记账数据集合；平台写入用户 Assets 目录下主文件与子文件。 |
| 解析 | 将上传的原始账单转为账本可消费的记录的过程。 |
| 映射 | 将账单描述等匹配到目标账户的规则。 |
| 账户 | Beancount 账户路径（如 Expenses:Food），表示资金分类。 |
| Fava | 基于 Beancount 的 Web 报表界面；自托管静态模式下由独立容器挂载用户 Assets 目录提供。 |
面向最终用户的展开说明见：核心概念。