环境变量索引

本文档列出 Forge Admin 前端与后端的环境变量与配置项。

前端环境变量

前端基于 Vite，环境变量定义在项目根目录的 .env* 文件中：

文件	用途
`.env.development`	开发环境配置（`pnpm dev` 时加载）
`.env.production`	生产环境配置（`pnpm build` 时加载）
`.env.example`	环境变量模板（可提交，本地复制后修改）

⚠️ 只有以 VITE_ 前缀开头的变量才会暴露给客户端代码。

管理端（forge-admin-ui）

变量名	说明	示例值
`VITE_HTTP_PORT`	开发服务器端口	`3000`
`VITE_REQUEST_PREFIX`	请求地址前缀	`/dev-api`（开发）/ `/forge-api`（生产）
`VITE_HTTP_PROXY_TARGET`	主服务代理地址（admin-server）	`http://127.0.0.1:8580/`
`VITE_FLOW_PROXY_TARGET`	流程服务代理地址（flow-server）	`http://127.0.0.1:8081/`
`VITE_RESOURCE_HOST`	图片 host 地址	`/`
`VITE_TEMPLATE_PATH`	模板文件下载地址	`/templates`
`VITE_APP_ID`	客户端 AppId	`pc`
`VITE_USER_CLIENT`	登录设备标识（oauth2 / 免登登录一致）	`pc`
`VITE_PUBLIC_PATH`	生产静态资源目录	`/forge`
`VITE_BASE_URL`	生产路由前缀	`/forge`

报表子系统单点登录与大屏兜底配置：

变量名	说明	示例值
`VITE_SSO_BRIDGE_ROUTE`	单点登录跳转路由	`/report/design`
`VITE_SSO_TARGET_CLIENT`	目标客户端编码	`forge_report`
`VITE_SSO_TARGET_BASE_URLS`	子系统前端入口地址映射（JSON）	`{"forge_report":"http://localhost:3021/forge-report"}`
`VITE_SSO_DEFAULT_REDIRECTS`	默认重定向（JSON）	`{"forge_report":"/project/items"}`
`VITE_REPORT_UI_BASE_URL`	大屏前端地址兜底	`http://localhost:3021/forge-report`
`VITE_REPORT_UI_DEFAULT_REDIRECT`	大屏默认重定向	`/project/items`
`VITE_REPORT_UI_HOST_FALLBACK`	大屏 host 兜底	`localhost:3021`
`VITE_REPORT_UI_PATH_PREFIX`	大屏路径前缀	`/forge-report`

移动端（forge-h5-ui）

变量名	说明	示例值
`VITE_HTTP_PORT`	开发服务器端口	`3001`
`VITE_REQUEST_PREFIX`	请求地址前缀	`/dev-api`
`VITE_HTTP_PROXY_TARGET`	App 服务代理地址（app-server）	`http://127.0.0.1:8583/`
`VITE_FLOW_PROXY_TARGET`	流程服务代理地址	`http://127.0.0.1:8081/`
`VITE_USER_CLIENT`	登录设备标识	`h5`
`VITE_APP_ID`	客户端 AppId	`forge_h5`

企业微信工作台免登已改为后端连接配置控制（sys_social_config.sso_workbench_enabled + connection_code），前端无需再配置。

后端 Spring Profiles

后端通过 Maven Profile 注入 Spring Profile（application.yml 中 spring.profiles.active: @profiles.active@）：

Profile	配置文件	用途
`local`	`application-local.yml`	本地开发
`dev`	`application-dev.yml`	开发环境
`prod`	`application-prod.yml`	生产环境

本地配置模板：复制 application-dev.example.yml 为 application-dev.yml（已 gitignore），填入 MySQL、Redis、AI 供应商等配置。

关键配置项

配置项	说明
`server.port`	服务端口（admin-server 默认 8580）
`spring.application.name`	应用名（如 `forge-admin-server`）
`spring.datasource.dynamic.datasource.master.url`	主数据源 JDBC 地址（动态数据源）
`spring.datasource.dynamic.datasource.master.username` / `password`	主数据源账号 / 密码
`spring.data.redis.host` / `port` / `password`	Redis 连接
`spring.data.redis.redisson.config`	Redisson 分布式锁配置

环境变量覆盖

环境变量	对应配置项	说明
`FORGE_FLYWAY_ENABLED`	`spring.flyway.enabled`	是否启用 Flyway 迁移
`FORGE_FLYWAY_LOCATIONS`	`spring.flyway.locations`	Flyway 迁移脚本扫描位置

Docker 环境变量

Docker 部署时通过环境变量覆盖默认配置（默认值见 docker-forge-admin/docker-compose.yml）：

环境变量	默认值	说明
`MYSQL_HOST`	`mysql`	MySQL 主机
`MYSQL_PORT`	`3306`	MySQL 端口
`MYSQL_DB`	`forge_admin`	数据库名
`MYSQL_USER`	`root`	数据库用户名
`MYSQL_PASSWORD`	`forge123456`	数据库密码
`REDIS_HOST`	`redis`	Redis 主机
`REDIS_PORT`	`6379`	Redis 端口
`REDIS_PASSWORD`	`forge123456`	Redis 密码
`JAVA_OPTS`	`-Xms256m -Xmx512m`	JVM 参数

加密与凭据相关（生产建议显式配置）：

环境变量	说明
`FORGE_CRYPTO_BOOTSTRAP_ENABLED` / `FORGE_CRYPTO_BOOTSTRAP_FILE`	密钥引导开关与引导文件
`FORGE_CRYPTO_SECRET_KEY`	加密密钥
`FORGE_CRYPTO_PERSISTENCE_ENABLED` / `WRITE_VERSIONED` / `LEGACY_READ_ENABLED`	持久化加密写版本 / 兼容读开关
`FORGE_CRYPTO_PERSISTENCE_ACTIVE_KEY_ID` / `ACTIVE_KEY`	当前活跃密钥 ID 与密钥
`FORGE_CRYPTO_PERSISTENCE_LEGACY_KEY`	兼容旧密钥
`FORGE_AUTH_LEGACY_CLIENT_SECRET_READ_ENABLED`	兼容旧客户端凭据读取

yaml

# docker-compose.yml 示例（节选）
services:
  forge-admin:
    image: forge-admin:latest
    environment:
      MYSQL_HOST: mysql
      MYSQL_PORT: 3306
      MYSQL_DB: forge_admin
      MYSQL_USER: root
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
      REDIS_HOST: redis
      REDIS_PASSWORD: ${REDIS_PASSWORD}
    ports:
      - "8580:8580"

环境变量索引 ​

前端环境变量 ​

管理端（forge-admin-ui） ​

移动端（forge-h5-ui） ​

后端 Spring Profiles ​

关键配置项 ​

环境变量覆盖 ​

Docker 环境变量 ​

相关文档 ​