配置与运维
本页说明 EasyNetBak 安装后的运行配置。安装方式请先阅读安装部署，API 接入配置请阅读 API 概览。
EasyNetBak 从项目根目录的 .env 读取配置；Docker Compose 也会将 .env 注入容器。建议以仓库中的 .env.example 或 .env.docker.example 为模板创建配置文件。
.env 可能包含数据库密码、Redis 密码、会话密钥和管理员密码。不要把真实 .env 提交到 Git、公开日志或工单系统。
配置优先级
数据库连接支持两种写法：
- 设置
DATABASE_URL，使用完整连接字符串； - 未设置
DATABASE_URL时，由DB_SCHEME、DB_HOST、DB_PORT、DB_USER、DB_PASSWORD和DB_NAME组合生成。
如果两种配置都没有完整的数据库信息，应用会回退到本地 SQLite sqlite:///./dev.db。这只适合开发或临时验证，生产环境应明确配置 PostgreSQL。
数据库
| 变量 | 默认值 | 说明 |
|---|---|---|
DATABASE_URL | — | 完整数据库连接字符串，优先级高于独立字段 |
DB_SCHEME | postgresql | 数据库协议 |
DB_HOST | — | 数据库主机名或地址 |
DB_PORT | 5432 | 数据库端口 |
DB_USER | — | 数据库用户名 |
DB_PASSWORD | — | 数据库密码 |
DB_NAME | — | 数据库名称 |
开发环境可以使用：
DATABASE_URL=sqlite:///./dev.db
生产环境建议使用独立 PostgreSQL 数据库账号，并为 DB_PASSWORD 设置随机、唯一的密码。
Redis 与 Celery
Redis 连接
| 变量 | 默认值 | 说明 |
|---|---|---|
REDIS_HOST | localhost | Redis 主机；Docker 环境通常为 redis |
REDIS_PORT | 6379 | Redis 端口 |
REDIS_PASSWORD | 空 | Redis 密码 |
REDIS_DB | 0 | Redis 数据库编号 |
CELERY_BROKER_URL | 自动生成 | 设置后覆盖由 Redis 参数生成的 Broker 地址 |
CELERY_RESULT_BACKEND | 使用 Broker 地址 | 设置后指定 Celery 结果存储地址 |
未直接设置 CELERY_BROKER_URL 时，应用会根据 REDIS_* 自动生成 redis://... 地址。
任务行为
| 变量 | 默认值 | 说明 |
|---|---|---|
CELERY_BACKUP_MAX_RETRIES | 1 | 备份任务最大重试次数 |
CELERY_BACKUP_RETRY_BACKOFF_SECONDS | 10 | 任务重试的退避基数，单位为秒 |
CELERY_TASK_SOFT_TIME_LIMIT_SECONDS | 0 | 软超时时间；0 表示不启用软超时 |
CELERY_TASK_TIME_LIMIT_SECONDS | 300 | 任务硬超时时间，单位为秒 |
CELERY_SCHEDULE_FINALIZE_POLL_SECONDS | 5 | 批量定时任务状态轮询间隔 |
CELERY_SCHEDULE_FINALIZE_MAX_POLLS | 720 | 批量定时任务最大轮询次数 |
CELERY_REDIS_SEMAPHORE_FAIL_OPEN | false | Redis 信号量异常时是否继续执行备份；生产环境建议保持 false |
调度器与多实例部署
| 变量 | 默认值 | 说明 |
|---|---|---|
ENABLE_SCHEDULER | true | 是否启用进程内调度器 |
单实例部署可以保持默认值。多 Web 实例部署时，只允许一个实例设置 ENABLE_SCHEDULER=true，其他实例应设置为 false，避免同一个计划被重复调度。
Celery Worker 不由该开关控制，Worker 仍需要单独运行或由 Docker Compose 编排。
安全与会话
| 变量 | 默认值 | 说明 |
|---|---|---|
SECRET_KEY | 开发示例值 | 用于会话和敏感数据保护；生产环境必须替换为随机长字符串 |
AUTH_COOKIE_NAME | nb_session | 会话 Cookie 名称 |
AUTH_COOKIE_SECURE | false | HTTPS 部署时应设置为 true |
AUTH_COOKIE_SAMESITE | lax | 会话 Cookie 的 SameSite 策略 |
AUTH_COOKIE_PERSISTENT | false | 是否让会话 Cookie 持久化 |
SESSION_TTL_SECONDS | 7200 | 会话有效期，单位为秒 |
BOOTSTRAP_ADMIN_USERNAME | admin | 首次初始化管理员用户名 |
BOOTSTRAP_ADMIN_PASSWORD | admin | 首次初始化管理员密码 |
BOOTSTRAP_ADMIN_USERNAME 和 BOOTSTRAP_ADMIN_PASSWORD 只用于初始化管理员。系统已经完成初始化后，修改这两个变量不会自动重置现有管理员账号。
生产环境至少应完成以下配置：
SECRET_KEY=replace-with-a-random-long-value
BOOTSTRAP_ADMIN_USERNAME=replace-with-your-admin-name
BOOTSTRAP_ADMIN_PASSWORD=replace-with-a-unique-strong-password
AUTH_COOKIE_SECURE=true
不要在系统已经保存凭据或运行会话后随意更换 SECRET_KEY。更换密钥会使已有会话失效，并可能影响已加密保存的数据读取。
CSRF 防护
| 变量 | 默认值 | 说明 |
|---|---|---|
CSRF_COOKIE_SAMESITE | lax | CSRF Cookie 的 SameSite 策略 |
CSRF_COOKIE_SECURE | false | HTTPS 部署时应设置为 true |
CSRF_COOKIE_KEY | fastapi-csrf-token | CSRF Cookie 名称 |
CSRF_COOKIE_PATH | / | CSRF Cookie 路径 |
CSRF_TOKEN_LOCATION | body | CSRF Token 的提交位置 |
CSRF_TOKEN_KEY | csrf_token | 请求中的 CSRF 字段名 |
公共 /api/v1/ 接口使用 API Key，不回退使用浏览器 Session Cookie；页面表单和内部 JSON 接口仍受 CSRF 防护约束。
时区与语言
| 变量 | 默认值 | 说明 |
|---|---|---|
TIMEZONE_OFFSET | +08:00 | 时间显示和部分任务处理使用的时区偏移 |
DEFAULT_LOCALE | zh-CN | 默认语言 |
SUPPORTED_LOCALES | zh-CN,en-US | 逗号分隔的支持语言列表 |
I18N_STRICT | false | 是否启用严格翻译检查 |
例如，使用英文作为默认语言：
DEFAULT_LOCALE=en-US
SUPPORTED_LOCALES=zh-CN,en-US
修改配置后的操作
普通环境变量修改不需要执行数据库迁移，但需要让对应服务重新读取 .env。
systemd 安装
sudo systemctl restart easynetbak-web easynetbak-worker
sudo systemctl status easynetbak-web easynetbak-worker
查看日志：
sudo journalctl -u easynetbak-web -u easynetbak-worker -f
Docker Compose
修改 .env 后重新创建服务：
docker compose up -d
docker compose ps
docker compose logs -f web
只有代码或依赖发生变化时，才需要追加 --build：
docker compose up -d --build
数据库迁移与版本升级
只有应用版本包含数据库结构变更时才需要执行 Alembic 迁移：
alembic upgrade head
使用安装脚本升级或使用 Docker Compose 部署新版本时，应以对应的升级步骤为准。升级前建议备份 PostgreSQL 数据库和 .env，不要把 alembic upgrade head 当作每次修改环境变量后的固定操作。