快速启动（后端）

在外层仓库根目录操作。fago/ 与 fago/fago-vben5/ 是子模块，空目录时先执行 git submodule update --init --recursive。

本页默认启动 MySQL 与 Redis。PostgreSQL 已接入迁移，但 compose 里的 postgres 服务带 poc profile，端口是 127.0.0.1:15432。一次部署只选择一种业务库。

前置条件

需要 Docker Compose、Go 引导工具链和仓库脚本。脚本固定 Go 1.27.3。下面的口令只在本机生成，不写入仓库，也不提供通用管理员密码。

启动依赖并迁移

在已 source scripts/go-env.sh 的前提下，也可用官方 CLI 起依赖：scripts/fago.sh dev up，再执行 scripts/fago.sh migrate（与下列 compose 命令等价）。

export FAGO_MYSQL_PASSWORD="$(openssl rand -hex 24)"
export FAGO_MYSQL_ROOT_PASSWORD="$(openssl rand -hex 24)"
docker compose -f deploy/compose/compose.yaml up -d mysql redis
export APP_ENV=development
export APP_DATABASE_DRIVER=mysql
export APP_DATABASE_DSN="fago:${FAGO_MYSQL_PASSWORD}@tcp(127.0.0.1:13306)/fago?charset=utf8mb4&parseTime=true&loc=UTC"
export APP_REDIS_ADDR=127.0.0.1:16379
export APP_HTTP_ADDR=127.0.0.1:8081
export APP_AUTH_COOKIE_PROFILE=development-http
export APP_AUTH_ORIGINS=http://127.0.0.1:5174
bash scripts/fago.sh migrate

development-http 在开发/测试只允许 loopback HTTP Origin。生产推荐 HTTPS 与浏览器实际看到的精确 Origin；HTTP 时 API 启动 WARN，刷新 Cookie 按 Origin 协议选用名称（见 登录与会话）。

迁移给当前库加上已发布结构。它使用数据库级锁、SQL 校验和和 dirty 标记。中途失败时先按 数据库迁移 处理，不要直接清掉 dirty 标记再继续。迁移和初始化不依赖 Redis；API 启动会同时检查 schema 和 Redis。

初始化第一个租户

租户尚不存在时才能执行。重复执行会失败并保留已有凭证。口令至少 14 个字符、最多 72 字节，只通过环境变量提供。

export BOOTSTRAP_TENANT_CODE=example
export BOOTSTRAP_TENANT_NAME=示例企业
export BOOTSTRAP_USERNAME=admin
read -r -s BOOTSTRAP_PASSWORD
export BOOTSTRAP_PASSWORD
bash scripts/fago.sh bootstrap
unset BOOTSTRAP_PASSWORD

默认 BOOTSTRAP_REALM=admin，创建的是租户身份。平台身份必须另设 BOOTSTRAP_REALM=platform，并单独提供口令。初始化会要求首次登录改密。

启动 API

bash scripts/fago.sh api

GET /api/health/live 只检查进程。GET /api/health/ready 检查数据库、schema 和 Redis；依赖失败返回 HTTP 503，业务码 503001。响应带 requestId。

worker 可以用 bash scripts/fago.sh worker 单独启动，使用同业务库的定时任务和站内通知循环，消息默认 Event、可显式配置 Redis Streams；未配置对象存储时通知仍执行。启用 S3 或 local 后另登记文件持久清理，所有循环在信号取消后一起等待退出。local 要求 worker 与 API 使用同一个预建目录。消息配置与积压指标见 可靠 worker，任务开通及运行恢复见 定时任务，通知开通与恢复见 站内通知与执行恢复。API 与 worker 使用相同存储配置，文件开通及规则见 文件与对象存储。配置项见 配置与环境。

按数据库构建

fago.sh 根据 FAGO_DATABASE_BUILD、APP_DATABASE_DRIVER、默认 mysql 的优先级选择构建目标。如果只在 YAML 中改为 PostgreSQL，应同时设置 FAGO_DATABASE_BUILD=postgres。应用在建立连接前检查配置与构建目标，不匹配时拒绝启动，不能临时切到另一种驱动。

# 当前项目只选择自己的业务库；例如 MySQL 项目。
export FAGO_DATABASE_BUILD=mysql
bash scripts/build-go.sh

只生成当前项目的一套产物，固定输出到 .cache/release/：fago-api、fago-worker、fago-cli 和 manifest.json。三个程序各司其职，不因数据库类型生成第二套目录。PostgreSQL 项目把构建变量设为 postgres，仍使用同一构建命令与输出位置。

每次只编译一个 OS/架构，默认当前平台；部署 Linux 时在该次构建前设置 GOOS=linux GOARCH=amd64 CGO_ENABLED=0。不会同时附带本机和 Linux 版本。发布构建固定使用 -trimpath -ldflags='-s -w' 去掉路径及调试符号，保留 Go 运行时错误栈；需用调试器时直接执行未精简的 go build。

每个二进制只链接当前数据库驱动，并只嵌入对应迁移 SQL；清单记录实际平台、依赖和 SHA-256。发布只取 .cache/release/，不复制源码、模块缓存、供应商目录或旧 .cache/bin/ 开发缓存。FAGO_BUILD_OUTPUT 可指定独立输出目录，验证脚本只用临时目录测试其他数据库，不留下另一套项目发布包。体积对照见 M3 实施记录。

商业库探针独立执行：db-poc.sh 用 FAGO_PROBE_DRIVER 选择 Oracle 或 SQL Server，探针只链接该驱动；达梦使用 dm-poc.sh。这些探针不随业务构建打包。达梦可作为第三种业务构建目标（FAGO_DATABASE_BUILD=dm / -tags=fago_dm），与 MySQL、PostgreSQL 一样通过 fago-cli migrate 应用 v13 全量业务 schema；达梦专用非管理员 schema 上的 31 项完整业务集成、逐版本迁移及真实 CLI/API 运行已通过；R4 生产认证、其他版本/集群和生产许可仍须独立确认。证据与范围见 数据库适配。

工作区与本地开发版本

go.work的use目录及各模块临时v0.1.0元数据均指向当前仓库，避免新缓存从旧开发版go.mod依赖图取数据。 新增模块时同步use与同版本replace；版本替换只覆盖已声明的本地模块，不覆盖第三方依赖。 独立验证仍用文件代理与真实require闭包，不使用workspace替换：

# 外层仓库根目录
python3 scripts/check-modules.py
bash scripts/test-backend.sh
bash scripts/test-independent.sh
# 结构检查拒绝use/开发版replace目录漂移；独立检查使用源码副本，不改原go.mod/go.sum。

不要为本地开发版本的校验和冲突关闭第三方验证或恢复旧源码缓存。先核对已声明的工作区映射与迁移/构建边界。