UnDercontrol · 自部署
配置参考
先用下面的生成器搭出一份可用配置，再到完整参考里查任何一项。每个配置项都有三种设置方式，优先级从高到低：CLI flag › 环境变量 › 内置默认值。工作目录下的 .env 文件会被自动加载。
事实来源：go-backend/internal/config/config.go——本页始终与它保持同步。
启动所需的最少配置
HOST_DOMAIN——http://localhost:3000或你的公网 URLJWT_SECRET—— 任意随机字符串（默认值是公开已知的）ADMIN_EMAIL—— 仅 Pro/Max 需要；Personal tier 不需要更多配置
生成你的配置
选择部署形态，右侧的命令、compose 文件和启动预览会实时更新。
版本
数据库
Pro/Max 功能文件存储
Pro/Max 功能AI 功能
HOST_DOMAIN
浏览器访问实例所用的 URL——下方的失败预览展示了它缺失或非法时的启动结果。
JWT_SECRET
已为你生成随机值——
docker run -d --name undercontrol \ -p 3000:8080 \ -e HOST_DOMAIN=http://localhost:3000 \ -e JWT_SECRET=37ba2f642e6393ecbb1f91fe94df3d303a50f4bc49ab8619 \ -v undercontrol-data:/app/data \ lintao0o0/undercontrol:latest
启动预览——成功
docker logs undercontrol==============================================================================
UnDercontrol v1.x.x is ready
--> Open http://localhost:3000 to get started
Login as: personal@undercontrol.local
default password: personal123 (set PERSONAL_TIER_PASSWORD to change it)
Tier: Personal (max users: 1)
Database: SQLITE
Storage: LocalFS
==============================================================================启动预览——配置错误
HOST_DOMAIN missing==============================================================================
STARTUP FAILED: configuration error
HOST_DOMAIN is required: set it to the external base URL clients use to
reach this backend (scheme + host, no trailing slash), e.g.
HOST_DOMAIN=https://app.example.com or HOST_DOMAIN=http://localhost:8080.
==============================================================================完整参考
点击变量名即可复制。
核心服务
客户端访问本实例的外部基础 URL——协议 + 主机，无尾部斜杠（如 https://ud.example.com，或映射 -p 3000:8080 时的 http://localhost:3000）。用于生成文件上传/下载链接，必须是浏览器实际使用的地址。缺失或格式非法 → 服务拒绝启动。
--host-domain服务监听端口。在 all-in-one 镜像中这是容器内部端口——用 -p <host>:8080 映射。端口被占用时会快速失败并给出明确报错。
8080--portdevelopment 或 production。production 会切换 HTTP 框架到 release 模式（减少请求日志）。all-in-one 镜像预置为 production。
development--environment日志级别：debug、info、warn、error。日志为结构化 JSON；无论什么级别，人类可读的启动 banner 都会打印。
info--log-levelSQL 语句日志：silent、error、warn 或 info（记录每条查询——仅调试用）。
silent--sql-log-level存放所有本地状态的目录：SQLite 数据库和本地存储的上传文件。Docker 中为 /app/data——在此挂载卷；备份该目录即备份整个实例。
./data--data-path账号与认证
用于签发登录 token 的密钥。默认值是公开已知的占位符——知道它的人可以伪造会话。任何非一次性的实例都必须设置一个足够长的随机值。
your-secret-key--jwt-secret访问 token 的有效期（分钟）。会话会自动刷新，实际影响是被盗 token 的存活时长。
60--jwt-expiration-minutes初始管理员账号的登录用户名，首次启动时创建。Pro/Max 缺少它会拒绝启动——Personal tier 忽略此项。
--admin-email初始管理员密码，仅在管理员账号首次创建时生效。首次登录后请修改（默认密码在用时启动 banner 会提醒）。
admin123--admin-password唯一用户 personal@undercontrol.local 的密码（登录名本身不可修改）。Start 自动登录始终读取该变量，但存储的密码只在首次启动时写入——只改一边会导致自动登录失效。请在首次启动前设置，或保持两边一致。
personal123--personal-tier-password一次性迁移开关。用 Personal tier 创建的数据库启动 Pro/Max 服务会被安全检查拒绝；设为 true（配合 ADMIN_EMAIL / ADMIN_PASSWORD）可把全部数据转移到新管理员账号并移除 personal 用户。
false--migrate-from-personal许可证Personal tier 不需要以下任何配置
解锁 Pro/Max 功能（多用户、PostgreSQL、S3、管理后台）的许可证 token。也可从 UNDERCONTROL_LICENSE、工作目录的 license.txt 或 /etc/undercontrol/license.txt 读取——先命中者生效。
--license-token与许可证 token 配套签发的 host secret。
--license-host-secret用于签发许可证。自部署实例请留空。
--license-private-key数据库默认 SQLite——PostgreSQL 为 Pro/Max 功能
sqlite 或 postgres。SQLite 位于 UD_DATA_PATH 内，对大多数个人/家庭实例已经足够；PostgreSQL 需要 Pro/Max 许可证。
sqlite--database-type完整的 PostgreSQL 连接串。设置后会覆盖下面所有单项 POSTGRES_* 变量。
--database-url不想用一条 URL 时的单项连接参数：POSTGRES_HOST（localhost）、POSTGRES_PORT（5432）、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DATABASE（undercontrol）、POSTGRES_SSL_MODE（disable）。
--postgres-host, --postgres-port, …连接池调优，默认值适合小型实例：最大连接 25、最大空闲 5、连接存活 300 秒、空闲超时 60 秒。
--postgres-max-open-conns, …文件与存储默认本地磁盘——S3 为 Pro/Max 功能
上传大小上限（字节）。
10485760 (10 MB)--max-file-size把上传文件存到 S3 兼容对象存储（AWS S3、Cloudflare R2、MinIO），替代本地数据目录。启动 banner 会显示当前生效的存储模式。
false--s3-enabledS3_ENABLED=true 后均为必填：endpoint URL、region（R2 可用 auto）、bucket、凭据。S3_FORCE_PATH_STYLE（默认 true）适合 MinIO 及多数非 AWS 提供商。
--s3-endpoint, --s3-bucket, …AI 与视觉全部可选——不配 key 时 AI 功能保持关闭
启用 AI 功能（图片转任务、票据识别、聊天）的 API key。兼容任何 OpenAI 风格的 endpoint——配合 OPENAI_BASE_URL 可接 Azure、GitHub Models 或本地模型服务。
--openai-api-key模型与 endpoint 调优：模型名（gpt-3.5-turbo）、base URL（https://api.openai.com/v1）、响应上限（1000 tokens）、temperature（0.7）、可选 organization ID。
--openai-model, --openai-base-url, …上面配置的系统级 AI 服务是否在后端默认激活 / 是否提供给前端。用户仍可在应用内使用自己的 AI 服务。
false / false--ai-startup-backend-active, …使用 Azure 而非 OpenAI 兼容视觉模型做图像分析时的 Azure 凭据。
--azure-vision-key, --azure-vision-url票据/文档文字提取的外部 OCR 服务：endpoint（http://127.0.0.1:8000/ocr）、认证 token、超时秒数（30）。
--ocr-endpoint, …网络与前端
允许从浏览器调用 API 的来源列表（逗号分隔）。仅当前端与后端不同源时需要——all-in-one 镜像前后端同源，默认值即可。
http://localhost:3000,http://localhost:12000,http://localhost:8080--cors-allowed-origins在浏览器之外（如桌面应用）生成分享链接时的指向。all-in-one 部署请设为与 HOST_DOMAIN 相同的公网 URL。
http://localhost:12000--frontend-url服务端通知（如备份结果）的 Slack incoming-webhook。
--slack-webhook-url后台任务
定时任务总开关（清理、备份、计划任务处理）。除非另跑独立 worker 实例，否则保持开启。
true--cron-enabled过期访客（演示）账号及其数据的自动清理：默认开启，保留 3 天，每天零点运行（0 0 * * *，cron 语法）。
--visitor-cleanup-enabled, …可观测性面向需要外送日志/追踪的运维者
通过 OpenTelemetry（OTLP）导出 trace、指标和日志。默认关闭；日志始终会输出到 stdout。
false--otel-enabled标准 OTLP 导出配置：共享 endpoint（OTEL_EXPORTER_OTLP_ENDPOINT）、认证头（OTEL_EXPORTER_OTLP_HEADERS）、按信号覆盖（OTEL_TRACES_ENDPOINT / OTEL_METRICS_ENDPOINT / OTEL_LOGS_ENDPOINT），以及上报的服务名（OTEL_SERVICE_NAME）。
--otel-endpoint, …进阶一般用不到
内部事件总线规模：后台 worker 数（4）与队列容量（1000）。只有异常繁忙的实例才值得调整。
--event-bus-workers, --event-bus-queue-size由 Onboarding Experience Owner 维护。config.go 中任何变量的新增、改名或默认值变化，都会在同一任务里同步到本页——发现不一致请当作 bug 反馈。另见自部署指南。