环境变量
配置分层（约定）
- 环境变量唯一事实源为各项目
.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 |
JWT_REFRESH_TOKEN_DAYS | 可选 | 30 | Refresh 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 |
AI 账本助手
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
ASSISTANT_DEEPSEEK_API_KEY | 可选 | 无 | 平台级 DeepSeek API Key；用户未在「输出配置 → BYOK」填写时作为回退（仅 Copilot，不用于云端解析） | both |
ASSISTANT_BASE_URL | 可选 | https://api.deepseek.com | 平台回退时的助手 API 基址 | both |
ASSISTANT_MODEL | 可选 | deepseek-v4-flash | 助手默认模型；DeepThink 通过 thinking 参数开启，不再切换 reasoner 模型 | both |
ASSISTANT_MAX_BQL_ROWS | 可选 | 100 | 单次 BQL 查询最大返回行数 | both |
ASSISTANT_MAX_BQL_RUNS | 可选 | 5 | 单次 BQL 查询最大执行次数 | both |
ASSISTANT_MAX_TOOL_ROUNDS | 可选 | 8 | 单次对话 LLM 工具调用轮次上限 | both |
用户侧在 输出配置 → BYOK 填写接口地址、模型与密钥。未填写时 Copilot 可回退平台 Key 聊天，云端解析不可用；填写后 Copilot 与账单分类共用这一把密钥。
AI 客户端（MCP）
| 变量名 | 必填级别 | 默认值（示例） | 说明 | 模板 |
|---|
MCP_RESOURCE_SERVER_URL | 条件必填 | 空 | MCP 端点对外地址（如 http://<主机>:38001/mcp）；留空则不校验访问令牌，生产必须配置 | deploy |
MCP_ISSUER_URL | 可选 | 空 | 令牌签发方地址；留空时复用 MCP_RESOURCE_SERVER_URL | deploy |
MCP_ALLOWED_HOSTS | 条件必填 | 127.0.0.1:*,localhost:*,[::1]:* | 端点 Host 白名单；不含客户端实际访问的域名与端口时返回 400 Invalid Host header | deploy |
MCP_ALLOWED_ORIGINS | 条件必填 | http://127.0.0.1:*,http://localhost:*,http://[::1]:* | 端点 Origin 白名单 | deploy |
MCP_OAUTH_REDIRECT_URI_SCHEMES | 可选 | http,https | 允许的 OAuth 回调 URL scheme；使用自定义 scheme 的客户端需追加 | deploy |
MCP_REQUIRED_SCOPES | 可选 | ledger:read | 访问令牌必须具备的 scope（逗号分隔） | deploy |
MCP_MAX_FILE_BYTES | 可选 | 1048576 | read_ledger_file 单文件读取上限（字节） | deploy |
MCP_AUTH_ENABLED | 可选 | true | 是否要求访问令牌；关闭后仅 MCP_DEV_USERNAME 可用 | — |
MCP_DEV_USERNAME | 可选 | 空 | 无令牌请求使用的本地开发用户 | — |
标记为 — 的变量未出现在模板中，仅在 settings.py 提供默认值；其余各项的注释见根目录 .env.example 的「MCP 服务（AI 客户端接入）」一节。
HTTP API
| 路径 | 说明 |
|---|
/api/docs/ | ReDoc 交互文档（经前端 Nginx 时与 Web 同源，例如 http://<主机>:38001/api/docs/） |
/api/schema/ | OpenAPI 3 Schema（JSON） |
/api/_allauth/ | allauth headless 接口根路径 |
/mcp | MCP Streamable HTTP 端点（AI 客户端接入，单 JSON 响应、无会话） |
/.well-known/oauth-protected-resource/mcp | RFC 9728 受保护资源元数据 |
/.well-known/oauth-authorization-server | RFC 8414 授权服务器元数据 |
/register | RFC 7591 动态客户端注册（DCR） |
/authorize、/token、/revoke_token | OAuth 2.1 授权码 + PKCE、令牌与撤销 |
认证请求头：Authorization: Bearer <access_token>。Access Token 有效期见 .env 中 JWT_ACCESS_TOKEN_HOURS（自托管以主仓模板为准）。Refresh Token 有效期与滑动续期窗口见 JWT_REFRESH_TOKEN_DAYS；刷新（POST /api/auth/token/refresh/）时会同时签发新的 refresh（滑动续期），客户端应保存响应中的 refresh 以便长期免登录。
MCP 与 OAuth 相关路径挂在域名根（不带 /api 前缀）。经前端 Nginx 转发时，/mcp 指向 MCP 服务、其余 OAuth 路径指向后端，对外只需暴露 38001 端口；服务部署与配置见 自托管。
线上示例：Beancount-Trans API（ReDoc）