配置参考

所有配置均通过环境变量设置。

控制平面（`muvee-server`）

变量	默认值	说明
`DATABASE_URL`	`postgres://muvee:muvee@localhost:5432/muvee?sslmode=disable`	PostgreSQL 连接字符串
`MIGRATIONS_DIR`	`./db/migrations`	SQL 迁移文件路径
`PORT`	`8080`	HTTP 监听端口
`BASE_DOMAIN`	`localhost`	根域名；项目以 `{prefix}.BASE_DOMAIN` 的形式对外提供服务。同时通过 `/api/agent/config` 下发给 Agent。
`BASE_DOMAINS`	—	可选，逗号分隔的额外根域名列表，让同一实例在多个 apex 域名下服务（多域名）。`BASE_DOMAIN` 仍为 canonical 默认值。详见下方多域名。
`GOOGLE_CLIENT_ID`	—	Google OAuth2 客户端 ID。设置后启用 Google 登录。详见 Google OAuth2。
`GOOGLE_CLIENT_SECRET`	—	Google OAuth2 客户端密钥
`GOOGLE_REDIRECT_URL`	`http://localhost:8080/auth/google/callback`	Google OAuth2 回调地址
`FEISHU_APP_ID`	—	飞书 / Lark App ID。设置后启用飞书登录。详见飞书 / Lark。
`FEISHU_APP_SECRET`	—	飞书 / Lark App Secret
`FEISHU_REDIRECT_URL`	`http://localhost:8080/auth/feishu/callback`	飞书 OAuth2 回调地址
`FEISHU_BASE_URL`	`https://open.feishu.cn`	飞书 API 基础地址。国际版 Lark 设置为 `https://open.larksuite.com`。
`WECOM_CORP_ID`	—	企业微信 CorpId（企业ID）。设置后启用企业微信登录。详见企业微信。
`WECOM_CORP_SECRET`	—	企业微信自建应用的 App Secret
`WECOM_AGENT_ID`	—	企业微信自建应用的 AgentId
`WECOM_REDIRECT_URL`	`http://localhost:8080/auth/wecom/callback`	企业微信 OAuth2 回调地址
`DINGTALK_CLIENT_ID`	—	钉钉 AppKey。设置后启用钉钉登录。详见钉钉。
`DINGTALK_CLIENT_SECRET`	—	钉钉 AppSecret
`DINGTALK_REDIRECT_URL`	`http://localhost:8080/auth/dingtalk/callback`	钉钉 OAuth2 回调地址
`ALLOWED_DOMAINS`	（允许所有）	允许登录的邮箱域名，逗号分隔（如 `company.com`）。仅对 Google 生效；飞书/企微/钉钉在无法获取真实邮箱时会生成合成地址（`*.local`），这类地址会自动跳过域名校验。
`ADMIN_EMAILS`	—	逗号分隔的邮箱地址列表，登录时自动提升为 `admin` 角色，可访问 `traefik.BASE_DOMAIN`
`JWT_SECRET`	`change-me-in-production`	用于签发 JWT 会话令牌的密钥
`AGENT_SECRET`	—	Agent ↔ 服务器认证的共享密钥（所有 Agent 上设置相同的值）。未设置时，Agent 端点无需认证（仅用于开发环境）。
`AUTH_SERVICE_URL`	`http://muvee-authservice:4181`	`muvee-authservice` 的内部 URL；在为 Traefik 生成项目级 ForwardAuth 配置时使用
`REGISTRY_ADDR`	`localhost:5000`	Docker 镜像仓库地址。通过 `/api/agent/config` 下发给 Agent——Agent 无需在本地设置此项。
`REGISTRY_USER`	—	镜像仓库基础认证用户名。下发给 Agent——Agent 启动时自动执行 `docker login`。
`REGISTRY_PASSWORD`	—	镜像仓库基础认证密码。下发给 Agent。
`SECRET_ENCRYPTION_KEY`	—	64 字符十六进制字符串（32 字节），用于以 AES-256-GCM 加密静态密钥。启用 Secrets 功能时必填。使用 `openssl rand -hex 32` 生成。
`VOLUME_NFS_BASE_PATH`	—	控制平面主机上用于项目工作区卷的 NFS 基础目录（如 `/mnt/nfs/volumes`）。每个项目的子目录会在该路径下自动创建。同时通过 `/api/agent/config` 下发给部署 Agent，Agent 使用该路径将卷 bind mount 到容器中。未设置时工作区功能不可用。
`DATASET_NFS_BASE_PATH`	—	数据集 NFS 基础目录（如 `/mnt/nfs/datasets`）。Dataset 的 `nfs_path` 会被视为该目录下的相对子路径（例如 `warehouse` → `/mnt/nfs/datasets/warehouse`）。相关机器需使用相同绝对路径挂载。控制平面 server 需要可写（`:rw`）——它不仅跑文件监控，还直接处理 dataset 文件操作（上传 / 删除 / 建目录 / 移动 / 复制），因此 NFS export 必须允许 server 主机写入。Deploy agent 只需要只读（`:ro`，用于 rsync 与 bind-mount 到用户容器）。

ForwardAuth 服务（`muvee-authservice`）

变量	默认值	说明
`PORT`	`4181`	HTTP 监听端口
`GOOGLE_CLIENT_ID`	—	与控制平面相同
`GOOGLE_CLIENT_SECRET`	—	与控制平面相同
`FORWARD_AUTH_REDIRECT_URL`	`http://localhost:4181/_oauth`	ForwardAuth 的 OAuth2 回调 URL。生产环境设置为 `https://BASE_DOMAIN/_oauth`，并在 Google Cloud Console 中与 `GOOGLE_REDIRECT_URL` 一起注册。
`BASE_DOMAIN`	—	根域名。必填，用于将 session cookie 共享给所有 `*.BASE_DOMAIN` 子域名（如 `traefik.BASE_DOMAIN`、各 project 子域名）。
`JWT_SECRET`	—	必须与控制平面的值一致
`ADMIN_EMAILS`	—	必须与控制平面的值一致；用于控制 `/verify-admin`（Traefik 控制台）访问权限

Agent（`muvee-agent`）

变量	默认值	说明
`NODE_ROLE`	（必填）	`builder` 或 `deploy`
`CONTROL_PLANE_URL`	`http://localhost:8080`	控制平面的内网地址（如 `http://10.0.0.1:8080`）。不要使用公开域名——详见 Agent 节点。
`AGENT_SECRET`	—	必须与控制平面上设置的值一致
`DATA_DIR`	`/muvee/data`	本地数据集缓存根目录（部署节点使用）
`HOST_IP`	（自动检测）	Traefik 用来访问此节点上容器的 IP 地址。自动从到达 `CONTROL_PLANE_URL` 所使用的网络接口检测。若自动检测结果有误（如多网卡主机），可手动覆盖。

镜像仓库凭据和 BASE_DOMAIN 自动下发

Agent 在启动时通过 GET /api/agent/config 从控制平面获取 REGISTRY_ADDR、REGISTRY_USER、REGISTRY_PASSWORD 和 BASE_DOMAIN。这些配置只需在控制平面上设置一次——无需在各个 Agent 节点上单独配置。

多域名

默认情况下 muvee 只在单个 BASE_DOMAIN 下服务。要让同一实例在多个 apex 域名下服务——例如一个海外域名和一个国内/ICP 域名——把 BASE_DOMAINS 设为逗号分隔的额外根域名列表：

BASE_DOMAIN=muveeai.com          # canonical 默认值
BASE_DOMAINS=muveeai.com,muvee.ai

BASE_DOMAIN 仍是 canonical 回退值（当请求 host 不匹配任何已配置域名时使用）。每个请求 muvee 会解析出 host 所属的根域名，因此以下都跟随用户实际所在的域名：

认证 cookie 按匹配到的根域名设置 Domain（在 muvee.ai 登录得到 .muvee.ai cookie，在其子域名间共享）。
OAuth redirect_uri rebase 到匹配的根域名，并保持每个域名单一 canonical host（如 https://app.muvee.ai/_oauth/google），使项目子域名仍经面板/authservice host 中转。
Traefik 路由用单条 OR 的 Host() 规则匹配每个项目/隧道前缀在各根域名下的 host，每个 host 各签一张证书。
CORS / 来源校验接受每个已配置根域名的 canonical 来源及其任一子域名。

每个额外根域名的前提

DNS：与 canonical 域名一样，把 <base>（A 记录）和 *.<base>（通配 A 记录）指向本服务器 IP。
TLS：额外根域名没有通配证书——每个项目子域名各自通过 Let's Encrypt HTTP-01 申请证书，因此该域名必须在 80 端口公网可达以完成 ACME 挑战。
OAuth Provider 后台：把每个域名的回调 URL 注册到你使用的每个 provider，如 https://app.<base>/auth/google/callback（控制面板登录）和 https://app.<base>/_oauth/google（per-project ForwardAuth）。

Cloudflare Tunnel 域名

根域名也可以改走 Cloudflare Tunnel，与 ACME 域名并存。证书由 Cloudflare 边缘持有，cloudflared 容器主动外连 Cloudflare，所以这个域名不需要开放任何端口，也不走 Let's Encrypt。其余根域名保持原样（DNS → 公网 :80/:443 → HTTP-01）。

BASE_DOMAINS=muveeai.com,example.net
CF_TUNNEL_DOMAINS=example.net      # 必须是 BASE_DOMAINS 中的一个
CF_TUNNEL_TOKEN=eyJhIjoi...        # 隧道的 connector token；填了就会启动 cloudflared

在 Cloudflare 后台（Zero Trust → Networks → Tunnels）创建隧道，把 token 填进 CF_TUNNEL_TOKEN。
给隧道加两个 Public Hostname：example.net 和 *.example.net，服务都填 http://localhost:8000。apex 的 CNAME 由 Cloudflare 自动创建；如果后台没有自动创建通配记录，就手动加一条 * CNAME 指向 <tunnel-id>.cfargotunnel.com。
在 SSL/TLS → Edge Certificates 打开 Always Use HTTPS。
拉取更新后的 traefik/traefik.yml（新增了内网入口 cftunnel），再执行 docker compose up -d。

工作方式：cloudflared 与 Traefik 共用网络命名空间，把请求转发到 Traefik 的 cftunnel 入口（:8000）。该入口是明文 HTTP，不映射到宿主机，并且只信任来自回环地址的 X-Forwarded-*，因此应用拿到的是真实客户端 IP 和 X-Forwarded-Proto: https。muvee-server 把隧道域名下的所有 host 都放到这个入口上，不配证书解析器。它还会为 <base> 和 app.<base> 生成面板路由和 /_oauth 路由，不需要额外的 compose label。后台「证书」面板中，这些 host 显示为「Cloudflare 托管」。

隧道域名的限制：

TCP 路由不可用：它依赖 :443 上的 SNI 透传，隧道不转发这类流量。ACME 域名上的 TCP 路由不受影响。
上传大小：Cloudflare Free / Pro 套餐单个请求体上限 100 MB。大文件 muveectl dataset push 请走 ACME 域名。隧道域名下不提供 registry.<base> 和 traefik.<base>。
二级子域名（如 a.b.example.net）不在 Cloudflare 免费 Universal SSL 证书的覆盖范围内。
与其他额外根域名一样，需要把隧道域名的 OAuth 回调注册到各个 provider。

运行时设置（管理员后台）

少数几个开关存放在 system_settings 表里，通过管理员后台编辑，而不是环境变量。改动无需重启即可生效。

键	默认值	说明
`auto_deploy_master_enabled`	`true`	两条自动部署触发路径的全局开关。
`auto_deploy_poll_interval_seconds`	`60`	外部仓库的 git 轮询间隔（最小 `10`）。
`auto_deploy_image_watch_interval_seconds`	`600`	compose 项目的 image-digest 轮询间隔（最小 `60`）。
`enabled_project_types`	(空)	允许创建的项目类型白名单，逗号分隔。留空 = 不作限制。

完整行为与项目级开关，详见自动部署。

限制可创建的项目类型

enabled_project_types 用来收窄这台平台允许新建哪些项目类型，在 管理员 → 设置 → 可创建的项目类型 里编辑。合法取值为 deployment、 compose、image、build、domain_only；留空表示全部允许（包括未来版本新增的类型）。

典型场景是控制面机器内存吃紧：deployment 和 build 都会在构建节点上跑 docker build，把白名单设成 compose,image,domain_only 就只保留那些直接拉现成镜像的类型。

这个检查只在创建时生效，且对所有人一视同仁，管理员也不例外。项目类型创建后不可更改，所以已经存在的、类型后来被禁用的项目照常部署——收窄白名单是拦住新增负载，不会弄坏已经在跑的东西。管理员如果需要某个被禁类型，先去设置页把它打开。

控制平面（muvee-server）​

ForwardAuth 服务（muvee-authservice）​

Agent（muvee-agent）​

多域名​

每个额外根域名的前提​

Cloudflare Tunnel 域名​

运行时设置（管理员后台）​

限制可创建的项目类型​