.env.example

# 白泽公开部署基础配置模板
#
# 推荐方式：
#   bash scripts/init-config.sh
#   或 bash scripts/install.sh
# 脚本会生成强随机密码、密钥和安全码。手工填写本文件时，请先复制为 .env。
#
# 文件边界：
#   - 本文件只保留首次部署和常规升级需要理解的基础项。
#   - 性能、队列、调度器、外部日志、AI 模型等低频调优项见 .env.advanced.example。
#   - 授权中心身份、签名材料、刷新周期和订阅升级入口不写入 .env；由白泽激活流程、系统托管配置和签名授权状态维护。
#
# 填写与引号规则：
#   - 每行使用 KEY=VALUE，不要写 export KEY=VALUE。
#   - 等号两边不要加空格。
#   - 空值写成 KEY=。
#   - 多个值用英文逗号分隔，例如 a.example,b.example。
#   - 数字和 true/false 不需要加引号。
#   - 密码、Token、URL 或命令如果包含空格、#、$、&、;、|、<、>、括号、反引号或反斜杠，优先使用单引号。
#   - 不建议用双引号包裹密钥；脚本 source .env 时，双引号内的 $ 和反引号仍可能被展开。
#   - 不要在变量行尾写内联注释，例如 KEY=value # comment。
# English version: .env.en.example

# 目的：脚本提示语言。
# 作用域：安装、升级、备份、恢复等公开部署脚本。
# 填写：zh 或 en；留 zh 可获得中文提示。
BAIZE_LANG=zh

# 目的：选择公开镜像和版本信息的下载来源。
# 作用域：首次安装配置。
# 填写：github 使用 GitHub 与 Docker Hub；acr 使用阿里云镜像和国内加速地址，中国大陆推荐 acr。
BAIZE_IMAGE_SOURCE=github

# 目的：PostgreSQL 容器首次初始化的账号。
# 作用域：docker compose 的 postgres 服务。
# 填写：通常保持 baize；改名后要同步 DB_USER。
POSTGRES_USER=baize

# 目的：PostgreSQL 容器首次初始化的账号密码。
# 作用域：postgres 容器和控制服务数据库连接。
# 填写：生产必须使用强随机值；包含特殊字符时使用单引号。
POSTGRES_PASSWORD=

# 目的：PostgreSQL 容器首次创建的数据库名。
# 作用域：docker compose 的 postgres 服务。
# 填写：通常保持 baize；改名后要同步 DB_NAME。
POSTGRES_DB=baize

# 目的：把 PostgreSQL 容器端口映射到宿主机。
# 作用域：docker compose 变量替换。
# 填写：默认 15432；同机多套部署时改为未占用端口。
POSTGRES_PUBLIC_PORT=15432

# 目的：指定 TimescaleDB 镜像。
# 作用域：docker compose 的 postgres 服务。
# 填写：通常由安装脚本按 BAIZE_IMAGE_SOURCE 自动选择。
BAIZE_POSTGRES_IMAGE=timescale/timescaledb:latest-pg16

# 目的：Redis 访问密码。
# 作用域：redis 容器和控制服务缓存连接。
# 填写：生产必须使用强随机值；包含特殊字符时使用单引号。
REDIS_PASSWORD=

# 目的：控制服务使用的 Redis 逻辑库编号。
# 作用域：控制服务进程。
# 填写：默认 0；共享 Redis 时可改为 1-15。
REDIS_DB=0

# 目的：把 Redis 容器端口映射到宿主机。
# 作用域：docker compose 变量替换。
# 填写：默认 16379；同机多套部署时改为未占用端口。
REDIS_PUBLIC_PORT=16379

# 目的：指定 Redis 镜像。
# 作用域：docker compose 的 redis 服务。
# 填写：通常由安装脚本按 BAIZE_IMAGE_SOURCE 自动选择。
BAIZE_REDIS_IMAGE=redis:7-alpine

# 目的：控制服务在容器内监听的地址。
# 作用域：控制服务进程。
# 填写：容器部署保持 0.0.0.0；不要改成只监听 127.0.0.1。
SERVER_HOST=0.0.0.0

# 目的：控制服务在容器内监听的端口。
# 作用域：控制服务进程和 docker compose 端口映射。
# 填写：默认 8080；通常只需要改 SERVER_PUBLIC_PORT。
SERVER_PORT=8080

# 目的：控制服务暴露到宿主机的端口。
# 作用域：docker compose 变量替换、安装检查、访问地址提示。
# 填写：默认 22501；远程 Agent 和控制台需要能访问该端口。
SERVER_PUBLIC_PORT=22501

# 目的：控制服务运行模式。
# 作用域：控制服务进程。
# 填写：生产保持 release；本地排障才临时使用 debug。
SERVER_MODE=release

# 目的：声明受信任的反向代理网段（IP 或 CIDR，多个用英文逗号分隔）。
# 作用域：docker compose 的 server 服务环境变量 SERVER_TRUSTED_PROXIES。
# 填写：通过反向代理访问时填写代理所在网段，例如 172.18.0.0/16；
# 留空表示不信任任何代理，客户端地址按直连连接识别。升级到 0.2.2 后该值默认为空，
# 之前部署在反向代理后面的环境需要显式配置，否则来源识别、频率限制和审计归属会基于直连地址生效。
SERVER_TRUSTED_PROXIES=

# 目的：选择控制服务镜像或本地发布包的 CPU 架构。
# 作用域：部署脚本和安装检查。
# 填写：amd64 或 arm64；脚本会按该值匹配发布产物。
SERVER_TARGET_ARCH=amd64

# 目的：Docker 运行控制服务时使用的平台。
# 作用域：docker compose 的 server 服务。
# 填写：linux/amd64 或 linux/arm64；必须与 SERVER_TARGET_ARCH 对应。
SERVER_TARGET_PLATFORM=linux/amd64

# 目的：选择部署产物来源。
# 作用域：部署脚本。
# 填写：公开安装保持 image，从所选镜像来源直接下载。
BAIZE_DEPLOY_MODE=image

# 目的：选择启动的服务组合。
# 作用域：部署脚本和 docker compose profile。
# 填写：full 启动控制服务和控制台；server-only 只启动控制服务。
BAIZE_STACK_MODE=full

# 目的：白泽公开发布版本。
# 作用域：镜像标签回退、版本脚本和发布清单对齐。
# 填写：通常随 releases/latest.json 更新；不要随意混用不同版本。
BAIZE_VERSION=0.2.1

# 目的：控制服务版本。
# 作用域：镜像标签、版本展示和升级检查。
# 填写：通常与发布清单保持一致。
BAIZE_SERVER_VERSION=0.2.1

# 目的：控制台版本。
# 作用域：控制台镜像标签、版本展示和升级检查。
# 填写：通常与发布清单保持一致。
BAIZE_WEB_VERSION=1.0.0

# 目的：控制服务镜像地址。
# 作用域：docker compose 的 server 服务。
# 填写：默认使用公开镜像；私有镜像地址包含特殊字符时使用单引号。
BAIZE_SERVER_IMAGE=ghcr.io/ysfl/baize-server:0.2.1

# 目的：控制台镜像地址。
# 作用域：docker compose 的 web 服务。
# 填写：默认使用公开镜像；私有镜像地址包含特殊字符时使用单引号。
BAIZE_WEB_IMAGE=ghcr.io/ysfl/baize-web:1.0.0

# 目的：控制台暴露到宿主机的端口。
# 作用域：docker compose 的 web 服务。
# 填写：默认 8088；server-only 模式不会使用。
WEB_PUBLIC_PORT=8088

# 目的：控制台容器内监听端口。
# 作用域：控制台容器。
# 填写：默认 8080；通常不需要修改。
WEB_CONTAINER_PORT=8080

# 目的：浏览器访问控制服务 API 的地址。
# 作用域：控制台运行时配置。
# 填写：同源部署保持 /api/v1；分离域名时填完整 https://.../api/v1。
WEB_API_BASE_URL=/api/v1

# 目的：控制台反向代理允许的请求体大小。
# 作用域：控制台容器。
# 填写：默认 100m；文件分发或导入场景需要更大时再调整。
WEB_CLIENT_MAX_BODY_SIZE=100m

# 目的：控制台容器访问控制服务的内部地址。
# 作用域：控制台容器。
# 填写：默认 server:8080；host 部署或分离部署时由脚本调整。
BAIZE_SERVER_UPSTREAM=server:8080

# 目的：控制台主域名快捷配置。
# 作用域：控制台入口 Host 检查。
# 填写：可选；设置后控制台只接受该域名访问。
BAIZE_WEB_DOMAIN=

# 目的：控制台允许访问的 Host 白名单。
# 作用域：控制台入口 Host 检查。
# 填写：可选；多个域名用英文逗号分隔，优先用于多域名部署。
BAIZE_WEB_ALLOWED_HOSTS=

# 目的：控制服务连接 PostgreSQL 的主机。
# 作用域：控制服务进程。
# 填写：容器部署保持 postgres；外部数据库填内网域名或 IP。
DB_HOST=postgres

# 目的：控制服务连接 PostgreSQL 的端口。
# 作用域：控制服务进程。
# 填写：容器内连接保持 5432；外部数据库按实际端口填写。
DB_PORT=5432

# 目的：控制服务连接 PostgreSQL 的账号。
# 作用域：控制服务进程。
# 填写：通常与 POSTGRES_USER 相同。
DB_USER=baize

# 目的：控制服务连接 PostgreSQL 的密码。
# 作用域：控制服务进程。
# 填写：通常与 POSTGRES_PASSWORD 相同；包含特殊字符时使用单引号。
DB_PASSWORD=

# 目的：控制服务连接的数据库名。
# 作用域：控制服务进程。
# 填写：通常与 POSTGRES_DB 相同。
DB_NAME=baize

# 目的：控制 PostgreSQL 连接是否启用 SSL。
# 作用域：控制服务进程。
# 填写：内置数据库保持 disable；云数据库按厂商要求填写 require/verify-full 等。
DB_SSLMODE=disable

# 目的：控制服务连接 Redis 的地址。
# 作用域：控制服务进程。
# 填写：容器部署保持 redis:6379；外部 Redis 填 host:port。
REDIS_ADDR=redis:6379

# 目的：是否启用浏览器跨域访问控制。
# 作用域：控制服务进程。
# 填写：控制台和 API 不同域名或端口时保持 true。
CORS_ENABLED=true

# 目的：允许访问 API 和 WebSocket 的浏览器 Origin。
# 作用域：控制服务进程。
# 填写：生产建议填写精确 Origin，例如 https://console.example.com；多个值用英文逗号分隔。
CORS_ALLOW_ORIGINS=*

# 目的：跨域请求是否允许携带凭证。
# 作用域：控制服务进程。
# 填写：默认 false；如果设为 true，CORS_ALLOW_ORIGINS 必须使用精确域名，不能使用 *。
CORS_ALLOW_CREDENTIALS=false

# 目的：用户登录 Token 的签名密钥。
# 作用域：控制服务进程。
# 填写：生产必须使用至少 32 位强随机值；修改后已登录会话会失效。
JWT_SECRET=

# 目的：首次安装的管理员账号。
# 作用域：控制服务初始化本地账号。
# 填写：默认 admin；首次登录后建议在控制台内修改密码。
ADMIN_USERNAME=admin

# 目的：首次安装的管理员初始密码。
# 作用域：控制服务初始化本地账号。
# 填写：生产必须使用强随机值；脚本生成后请妥善保管。
ADMIN_PASSWORD=

# 目的：资产凭据、通知配置等敏感数据的加密主密钥。
# 作用域：控制服务进程。
# 填写：生产必须使用至少 32 位强随机值并离线备份；修改会导致旧密文不可读。
CREDENTIAL_MASTER_KEY=

# 目的：主机画像刷新和命令历史明文查看的安全码哈希。
# 作用域：控制服务高敏操作安全保护。
# 填写：生产推荐使用哈希值；设置后可清空明文安全码。
BAIZE_HOST_PROFILE_SECURITY_CODE_HASH=

# 目的：主机画像刷新和命令历史明文查看的明文安全码。
# 作用域：首次部署或重置时使用。
# 填写：脚本会生成随机值；生产稳定后建议改用哈希并清空明文。
BAIZE_HOST_PROFILE_SECURITY_CODE=

# 目的：是否由控制服务自己终止 TLS。
# 作用域：控制服务进程。
# 填写：使用 Nginx、Caddy 或负载均衡终止 HTTPS 时保持 false。
TLS_ENABLED=false

# 目的：TLS 证书 PEM 文件路径。
# 作用域：控制服务进程，仅 TLS_ENABLED=true 时使用。
# 填写：容器内可读路径；生产更推荐在反向代理层处理 TLS。
TLS_CERT_FILE=

# 目的：TLS 私钥 PEM 文件路径。
# 作用域：控制服务进程，仅 TLS_ENABLED=true 时使用。
# 填写：容器内可读路径，权限应限制为控制服务可读。
TLS_KEY_FILE=

# 目的：Agent 发布包在控制服务容器内的目录。
# 作用域：控制服务远程安装和升级入口。
# 填写：容器部署保持 /app/agent/dist。
AGENT_ARTIFACT_DIR=/app/agent/dist

# 目的：Linux/macOS Agent 安装脚本路径。
# 作用域：控制服务生成安装命令和下载入口。
# 填写：容器部署保持 /app/agent/dist/install.sh。
AGENT_INSTALL_SCRIPT_PATH=/app/agent/dist/install.sh

# 目的：Windows Agent 安装脚本路径。
# 作用域：控制服务生成安装命令和下载入口。
# 填写：容器部署保持 /app/agent/dist/install.ps1。
AGENT_INSTALL_POWERSHELL_PATH=/app/agent/dist/install.ps1

# 目的：Agent 能访问到的控制服务外部地址。
# 作用域：Agent 注册、安装、升级和下载链接。
# 填写：上线前必须改成真实 IP 或域名，不要带结尾斜杠；本机执行器不依赖此地址。
AGENT_PUBLIC_SERVER_URL=http://127.0.0.1:22501

# 目的：部署完成后是否自动安装本机执行器。
# 作用域：公开部署脚本。
# 填写：默认 true；脚本只在具备主机权限时自动安装，否则会跳过并给出手动命令。
BAIZE_SERVER_HOST_AGENT_ENABLED=true

# 目的：本机执行器连接控制服务的内部地址。
# 作用域：公开部署脚本自动安装本机执行器。
# 填写：默认留空，由脚本使用 http://127.0.0.1:${SERVER_PUBLIC_PORT}；只有端口映射特殊时才填写。
BAIZE_SERVER_HOST_AGENT_INTERNAL_URL=

# 目的：自动生成升级临时令牌的有效期。
# 作用域：控制服务远程升级流程。
# 填写：单位小时；默认 24，安全要求更高可调低。
AGENT_UPGRADE_AUTO_TOKEN_TTL_HOURS=24

# 目的：登录纳管声明中的官网地址。
# 作用域：控制服务下发给 Agent。
# 填写：默认官方地址；常规部署不需要修改。
BAIZE_LOGIN_NOTICE_OFFICIAL_SITE_URL=https://baize.run

# 目的：登录纳管声明中的社区入口。
# 作用域：控制服务下发给 Agent。
# 填写：默认官方社区地址；常规部署不需要修改。
BAIZE_LOGIN_NOTICE_DISCORD_URL=https://discord.gg/UMR7mnZFqh

# 目的：登录纳管声明中的 Telegram 社区入口。
# 作用域：控制服务下发给 Agent。
# 填写：默认官方社区地址；常规部署不需要修改。
BAIZE_LOGIN_NOTICE_TELEGRAM_URL=https://t.me/+y3n_66PfRSw0ZDRl

# 目的：登录纳管声明中的支持入口。
# 作用域：控制服务下发给 Agent。
# 填写：支持 http(s) URL 或 mailto；包含查询串时使用单引号。
BAIZE_LOGIN_NOTICE_SUPPORT_URL=mailto:support@baize.run

# 目的：登录纳管声明中的滥用上报入口。
# 作用域：控制服务下发给 Agent。
# 填写：支持 http(s) URL 或 mailto；包含查询串时使用单引号。
BAIZE_LOGIN_NOTICE_ABUSE_REPORT_URL=mailto:support@baize.run

# 目的：允许禁用登录纳管声明的部署级解除密钥哈希。
# 作用域：控制服务高敏安全保护。
# 填写：为空表示禁止禁用；仅在官方确认后填写 64 位 SHA-256。
BAIZE_LOGIN_NOTICE_DISABLE_SECRET_SHA256=

# 目的：登录纳管声明禁用事件的上报地址。
# 作用域：控制服务风控上报。
# 填写：默认官方地址；上报失败不影响本地审计。
BAIZE_LOGIN_NOTICE_REPORT_ENDPOINT=https://baize.run/api/v1/security/login-notice/disable-events

# 目的：登录纳管声明禁用事件上报令牌。
# 作用域：控制服务风控上报。
# 填写：可选；包含特殊字符时使用单引号。
BAIZE_LOGIN_NOTICE_REPORT_TOKEN=

# 目的：离线城市库路径。
# 作用域：控制服务 IP 归属解析。
# 填写：容器部署保持该路径；本地库缺失时先执行 GeoIP 安装脚本。
GEOIP_CITY_MMDB_PATH=/app/runtime/geoip/dbip-city-lite.mmdb

# 目的：离线 ASN 库路径。
# 作用域：控制服务 IP 归属解析。
# 填写：容器部署保持该路径；本地库缺失时先执行 GeoIP 安装脚本。
GEOIP_ASN_MMDB_PATH=/app/runtime/geoip/dbip-asn-lite.mmdb

# 目的：是否只使用离线 GeoIP/ASN 库。
# 作用域：控制服务 IP 归属解析。
# 填写：生产建议 true，避免运行期访问公网查询服务。
GEOIP_OFFLINE_ONLY=true

# 目的：首次部署时是否自动准备离线 GeoIP 数据库。
# 作用域：公开部署脚本。
# 填写：默认 true；网络不可用时脚本会给出警告并继续部署核心服务。
BAIZE_AUTO_INSTALL_GEOIP=true

# 目的：是否写入本地滚动运行日志。
# 作用域：控制服务进程。
# 填写：生产建议 true，便于诊断和离线排障。
BAIZE_RUNTIME_LOG_FILE_ENABLED=true

# 目的：运行日志目录。
# 作用域：控制服务进程。
# 填写：容器部署保持 /app/data/logs/baize-server。
BAIZE_RUNTIME_LOG_DIR=/app/data/logs/baize-server

# 目的：单个运行日志文件大小上限。
# 作用域：控制服务进程。
# 填写：单位 MB；默认 50。
BAIZE_RUNTIME_LOG_FILE_MAX_SIZE_MB=50

# 目的：本地滚动日志文件保留数量。
# 作用域：控制服务进程。
# 填写：默认 7；磁盘较小时可调低。
BAIZE_RUNTIME_LOG_FILE_MAX_FILES=7

# 目的：是否启用运行日志热索引。
# 作用域：控制服务进程。
# 填写：默认 true；极低资源环境可关闭。
BAIZE_RUNTIME_LOG_INDEX_ENABLED=true

# 目的：当前发布清单路径。
# 作用域：控制服务版本展示和升级检查。
# 填写：容器部署保持 /app/releases/manifest.env。
BAIZE_RELEASE_MANIFEST_PATH=/app/releases/manifest.env

# 目的：控制服务构建信息路径。
# 作用域：版本展示、诊断和升级检查。
# 填写：容器部署保持 /app/server/dist/build-info.env。
BAIZE_SERVER_BUILD_INFO_PATH=/app/server/dist/build-info.env

# 目的：Agent 构建信息路径。
# 作用域：版本展示、诊断和升级检查。
# 填写：容器部署保持 /app/agent/dist/build-info.env。
BAIZE_AGENT_BUILD_INFO_PATH=/app/agent/dist/build-info.env

# 目的：远端最新版本清单。
# 作用域：版本检查和升级提示。
# 填写：默认公开清单；私有镜像部署可改为自有清单 URL。
BAIZE_LATEST_MANIFEST_URL=https://raw.githubusercontent.com/ysfl/baize/main/releases/latest.json

# 目的：远端更新日志清单。
# 作用域：版本详情展示。
# 填写：默认公开清单；私有镜像部署可改为自有清单 URL。
BAIZE_RELEASE_CHANGELOG_URL=https://raw.githubusercontent.com/ysfl/baize/main/releases/changelog.json

# 目的：宿主机自动更新组件写入的当前版本状态。
# 作用域：控制服务版本展示；容器内只读。
# 填写：容器部署保持 /app/runtime/release/current.json。
BAIZE_RUNTIME_RELEASE_STATE_PATH=/app/runtime/release/current.json

# 目的：单个中心服务或管理界面镜像更新的最长等待时间。
# 作用域：受控自动更新任务。
# 填写：60 到 3600 秒，默认 900。
BAIZE_IMAGE_UPGRADE_TIMEOUT_SEC=900

# 目的：控制服务启动时是否自动更新数据库结构。
# 作用域：控制服务进程。
# 填写：单实例部署保持 true；多实例滚动发布由外部数据库更新流程接管时可设 false。
BAIZE_DB_AUTO_MIGRATE=true

# 目的：备份根目录。
# 作用域：备份、恢复、清理和重新初始化脚本。
# 填写：留空时使用每个安装目录的默认备份位置；建议放在安装目录外。
BAIZE_BACKUP_DIR=

# 目的：备份保留天数。
# 作用域：备份清理脚本和定时备份脚本。
# 填写：默认 14；合规要求更长时调大，并确认磁盘容量。
BAIZE_BACKUP_KEEP_DAYS=14