# fago

**Repository Path**: nymondo/fago

## Basic Information

- **Project Name**: fago
- **Description**: 适合AI时代的开发框架。Fago是一套用Go编写的多模块开发框架，适合AI开发，项目符合二级等保要求。工作流使用纯Go实现，功能和Flowable一致
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-10-22
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="fago-server/assets/fago-logo.png" alt="Fago" width="420">
</p>

# Fago

<p align="center">
  <img src="https://img.shields.io/badge/Go-1.27.3-00ADD8.svg" alt="Go 1.27.3">
  <img src="https://img.shields.io/badge/Gin-1.12.0-blue.svg" alt="Gin 1.12.0">
  <img src="https://img.shields.io/badge/GORM-1.31.1-blue.svg" alt="GORM 1.31.1">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT">
</p>

适合 AI 时代的开发框架。**Fago** 是一套用 Go 编写的企业后台，前端使用 Vben 5 的 web-antd。应用层按网络安全等级保护第二级建设；生产内容加密默认 RSA，可选 SM2/SM4 套件。系统管理、基础设施和业务模块分开，API 与 worker 分进程运行，工作流使用纯 Go 实现，默认部署不需要 JVM。语言取舍见下文「选择 Go」。

当前模块版本为 **v0.1.0**，已发布结构为 schema **v26**。到 2026-10-28，M0 到 M5 的本地工程与自动化验收已经完成；M1、M2 另有用户人工确认。下文「已交付」表示本仓库对应代码可以在本地运行。「建设中」「试验」和「规划」尚未作为完整产品交付。当前没有生产环境，未执行生产部署。

本仓库包含后端 `fago-server/` 与前端 `fago-vben5/`。后端命令在 `fago-server/` 下执行，Go 模块由该目录的 `go.work` 组装，共 23 个成员。CLI 位于 `fago-server/apps/fago-cli/`，二进制名 `fago-cli`，说明见 [CLI](fago-server/apps/fago-cli/README.md)。若在包含 `scripts/go-env.sh` 的外层编排仓库里开发，先在该仓库根目录执行 `source scripts/go-env.sh`，再进入 `fago-server/`；`fago.local/*` 未发布到公网，缺少这个环境时模块解析会失败。

## 新手必读

* 许可：[LICENSE](LICENSE)
* 二级等保、Go 与开箱即用：见下文同名小节
* 模块划分：见下文「模块」
* 启动：见下文「启动」
* 入口命令：`fago-server/apps/fago-server/cmd/api`、`fago-server/apps/fago-server/cmd/worker`、`fago-server/apps/fago-cli/cmd/fago-cli`
* 前端应用：`fago-vben5/apps/web-antd`

## 版本说明

| 版本 | 说明 |
| --- | --- |
| v0.1.0 | Go 1.27.3 workspace，23 个模块，schema v26。已交付工程底座、MySQL / PostgreSQL 迁移、身份与会话、租户内系统管理、平台租户与套餐、字典参数、文件、通知、定时任务、受限代码生成，以及多用户、多终端和本地 OIDC SSO。通用工作流、其余数据库和消息后端尚未作为产品交付 |

模块路径使用本地命名空间 `fago.local/fago`。各 `go.mod` 中的依赖版本为 v0.1.0。

## 平台简介

Fago 面向需要自建管理后台的团队，后端按下面的范围建设：

* Go workspace 多模块、Gin、GORM；API 与 worker 分进程部署
* 业务库当前装配 MySQL 与 PostgreSQL，每次部署选择一种
* 租户身份、平台身份、会员和服务账号分开；菜单、按钮和数据范围在服务端判断，权威数据留在业务库。Redis 用于登录限流和生产请求号去重
* 租户开通、初始化、停用、恢复、到期、套餐能力上限和账号配额已可在本地运行
* 字典、参数、通用 S3 文件、站内通知、定时任务和 Event / Redis Streams 可靠任务已可在本地运行
* 浏览器双应用 SSO、故障补偿和签名退出已在本地验证；原生客户端目前是 macOS 上的有限验收命令
* 工作流模块在仓库中，目前是有界持久化试验，不是可交付的审批产品
* 显式数据库迁移和初始化，不提供通用管理员密码
* 应用层按网络安全等级保护第二级建设

MySQL 与 PostgreSQL 已接入迁移和运行时。达梦 adapter 位于 `fago-server/adapters/database/fago-dm`，默认 API 不引入；开发实例上的行为验证不代替后续版本认证。商业库探针位于 `fago-server/poc/fago-database`。`fago-server/poc/fago-oidc` 保留早期试验；当前 SSO 运行面在身份模块和 API 中。

## 符合二级等保

Fago 按照 GB/T 22239-2019《信息安全技术 网络安全等级保护基本要求》**第二级**建设应用安全，应用层对应身份鉴别、访问控制、安全审计和默认安全配置。

| 二级要求 | Fago 的对应做法 |
| --- | --- |
| 身份鉴别 | 账号唯一标识；口令使用 bcrypt 保存；登录失败对外统一为凭证错误；连续失败锁定账户；口令有长度、复杂度和有效期。到期后只能走受限改密 |
| 登录超时 | 会话空闲超时与刷新凭证分开；必须改密的会话有绝对期限，刷新不会把期限往后推 |
| 访问控制 | 菜单、按钮和数据范围在服务端判断；租户之间隔离；平台身份、租户身份、会员和服务账号不共用凭证 |
| 安全审计 | 登录、失败、锁定、改密和会话撤销留下审计原因；日志和错误响应不包含口令、token 或数据库连接串 |
| 默认安全 | 没有通用管理员密码；初始化口令至少 14 个字符且不超过 72 字节。`development-http` 只允许开发或测试的 loopback；生产可以使用 HTTP Origin，启动时给出 HTTPS 警告 |

定级、备案和测评在实际交付的系统上，由使用单位委托具备资质的机构完成。主机加固、边界防护、备份介质和安全管理制度由部署方与使用单位承担。内容加密默认套件是 RSA；SM2/SM4 是可选套件。TLCP、口令 SM3 和商用密码产品认证尚未实现。

## 选择 Go

Vibe Coding 里，模型和人要反复读、改同一份后端代码。Fago 使用 Go，主要因为三件事：**bug 更少，AI 读得懂，隐式行为少。** 下面用这三件事比较 Go、Java / Kotlin、Python、TypeScript（Node）和 Rust。

| | Go | Java / Kotlin | Python | TypeScript（Node） | Rust |
| --- | --- | --- | --- | --- | --- |
| 少 bug | 语法面小，控制流直。静态类型拒绝不存在的函数和错误字段；`error` 写在返回值里，失败路径不容易被吞掉。空指针和并发仍要人看，但大量「看起来能跑、跑起来才错」的问题在编译时就停住 | 静态类型同样能挡住错误 API。注解、反射、依赖注入和切面里的错误编译期看不见，生成代码常常要跑起来才发现装配错了 | 模型写得很快。类型默认不强制，逻辑错误、弄错的字段和没处理的异常留到运行时，bug 更多靠测试事后发现 | 类型能挡住一部分错误。`any`、不完整的类型声明，以及装饰器在运行时才生效的行为，会让 bug 漏过检查 | 运行时 bug 最少。模型经常过不了借用检查，改了很多轮仍然编译失败，错误从「线上 bug」变成「写不完」 |
| AI 能看懂 | 一个函数里就能看完数据从哪来、到哪去。关键字少，`gofmt` 只有一种版式，模型续写和人审查用的是同一份直线代码 | 业务代码往往要连着注解、配置和另一个类的隐式装配一起读。模型能模仿样例，却不容易从眼前这个文件判断实际会执行什么 | 语法好读。行为若藏在元类、装饰器或框架约定里，模型只看当前函数会漏掉真正执行的分支 | 语法模型最熟。一个请求的真实路径可能散落在装饰器、依赖注入和打包配置里，只读函数体不够 | 类型把约束写全了，信息密度高。所有权、生命周期和 trait 让模型很难从一段代码稳定推断「改这里会牵动哪里」 |
| 隐式行为 | 少。HTTP 处理、数据库调用、事务和并发都出现在调用处。Fago 用显式构造器装配模块，不靠全局容器在运行时把实现注入进来 | 多。约定大于配置、自动配置、AOP 会在源码以外改变请求的结果 | 视框架而定。装饰器、信号和元类会在函数体外追加行为 | 偏多。装饰器、中间件注册和依赖注入经常不写在业务函数里面 | 少。代价是这些约束都堆在类型系统里，模型要同时看懂类型和函数体 |

这三件事是连着的。隐式行为少，AI 才读得懂当前文件；读得懂，才不会补出一条实际不会执行、或者会在别处偷偷执行的逻辑；逻辑都在明处，编译器又能拒绝错误的类型，生成结果里的 bug 就更少。

Java、Python 和 TypeScript 的公开样例更多，模型第一次落笔往往更顺。Rust 把更多错误留在编译期，运行起来之后的意外更少。Go 换来的是：模型面对的代码和进程真正执行的代码更接近，所以更适合人和 AI 一起改企业后台。

Fago 采用 Go 1.27.3、Gin 和 GORM。模块由 `fago-server/apps/fago-server` 显式装配，工作流也放在同一套进程模型里。

## 开箱即用

准备好 MySQL 或 PostgreSQL 以及 Redis，在 `fago-server/` 设置环境变量，即可依次完成迁移、初始化和启动。模块已经在 `go.work` 里装配好，不需要再拼依赖或生成工程骨架。

三个进程入口：常驻的 `api`、`worker`，以及一次性运维的 `cli`。

| 命令 | 拿到的结果 |
| --- | --- |
| `go run ./apps/fago-cli/cmd/fago-cli migrate` | 当前库的结构到达已发布版本 |
| `go run ./apps/fago-cli/cmd/fago-cli bootstrap` | 出现第一个租户和管理员，并带上必须改密标记 |
| `go run ./apps/fago-cli/cmd/fago-cli gen-encryption-key -output <path>` | 生成生产 API 内容加密 RSA 私钥（无需数据库） |
| `go run ./apps/fago-server/cmd/api` | HTTP 服务开始监听，健康检查可以访问 |
| `go run ./apps/fago-server/cmd/worker` | 后台进程独立运行，处理定时任务、站内通知和已配置的可靠消息，并可以优雅退出 |

以上命令的工作目录是 `fago-server/`。`APP_DATABASE_DRIVER` 在 `mysql` 和 `postgres` 之间切换即可换库，应用代码不用改。具体环境变量见下文「启动」。前端在 `fago-vben5/`，本地页面 Origin 需与开发配置一致，示例为 `http://127.0.0.1:5174`。

## 开源协议

本项目采用 [MIT License](LICENSE)。个人与企业可以免费使用、修改和再分发；再分发时保留版权声明和许可文本。前端快照保留 Vben 依赖闭包和 MIT 许可。

## 功能地图

| 标记 | 含义 |
| --- | --- |
| 已交付 | 本仓库中的对应代码可以在本地运行，并有自动化验收 |
| 建设中 | 已有部分实现，尚未形成完整功能 |
| 试验 | 仓库里有探针或有界试验，不能当作产品功能 |
| 规划 | 属于平台方向，本仓库尚未提供该功能 |

本地验收不等于生产部署。生产网络、主机、容量和恢复目标仍待有环境后单独验收。

### 系统功能

| 功能 | 描述 | 进度 |
| --- | --- | --- |
| 登录认证 | 口令登录、刷新、登出、改密、会话撤销；access token 与 HttpOnly 刷新 cookie。租户身份与平台身份分开 | 已交付 |
| 账户安全 | 连续失败锁定、会话空闲、口令长度与复杂度、必须改密和口令有效期。租户可继承或覆盖策略，并解锁账号 | 已交付 |
| 个人权限 | 当前用户、权限码、动态菜单。按钮与菜单使用同一服务端权限码 | 已交付 |
| 用户管理 | 用户查询、启停、重置密码、多角色、版本冲突检查 | 已交付 |
| 部门管理 | 组织树、防环、删除保护 | 已交付 |
| 岗位管理 | 用户所属岗位 | 已交付 |
| 角色管理 | 角色、菜单授权、按钮权限；保留角色不能普通改授权 | 已交付 |
| 数据权限 | 按角色上的具体权限取本人、本部门、部门子树、自选部门或本租户全部 | 已交付 |
| 租户管理 | 待初始化创建、幂等初始化、停用、恢复、到期续期和平台审计 | 已交付 |
| 租户套餐 | 能力与权限上限、账号配额；降级保留已有数据并阻止超额新增 | 已交付 |
| 操作审计 | 登录、失败、撤销和关键变更留痕；操作日志与登录日志按权限查询，出口脱敏 | 已交付 |
| 字典与参数 | 显式复制全局模板、租户独立维护；敏感参数只替换、不回显 | 已交付 |
| 站内通知 | 模板与发送快照、幂等、本人收件箱、死信管理和 Event worker | 已交付 |
| 定时任务 | 一次性和固定间隔、人工新执行、租约恢复与执行历史 | 已交付 |
| 文件服务 | 租户内上传、授权下载和删除；通用 S3 endpoint，或单机预建目录。本地已与 RustFS 联调，其他对象存储厂商未逐一认证。local 不用于未共享目录的多副本 | 已交付 |
| 代码生成 | 受限模板 `tenant-crud-v1`：导入、配置、预览、下载，并在双库完成 CRUD。任意资源和达梦生成模板未交付 | 已交付 |
| 身份客户端 | 平台维护客户端、会话上限、配置版本和本人全设备退出 | 已交付 |
| 会员账号 | 独立会员主体与会话、管理员再鉴别、首次改密、刷新重放、设备撤销和本人注销 | 已交付 |
| 服务账号 | 独立机器凭据、轮换、启停和 scope；含字典只读消费者 | 已交付 |
| 认证模式 | 平台、租户后台和会员可选仅口令、口令或 SSO、仅 SSO；最后绑定和恢复管理员有保护 | 已交付 |
| 浏览器 SSO | Vben 登录、刷新、重载，以及本地双应用登录、IdP 故障补偿和签名退出 | 已交付 |
| 原生 SSO | 系统浏览器 PKCE、内存会话和本地 / RP 退出。macOS 有限命令已验证；Linux、Windows 和长期凭据缓存未交付 | 已交付 |
| Excel | 通用导入与导出 | 规划 |
| WebSocket | 实时通道 | 规划 |

### 基础设施

| 功能 | 描述 | 进度 |
| --- | --- | --- |
| 健康检查 | `GET /api/health/live` 检查进程，`GET /api/health/ready` 检查数据库、schema 和 Redis | 已交付 |
| 数据库迁移 | MySQL、PostgreSQL 显式迁移，带库级锁、SQL 校验和与 dirty 标记。当前已发布版本为 schema v26 | 已交付 |
| 初始化 | 显式创建初始租户和管理员。口令至少 14 个字符、不超过 72 字节，只从环境变量读取 | 已交付 |
| 配置与日志 | 环境配置、结构化日志、敏感字段脱敏、生产 JWE、可选 SM2/SM4 套件、优雅退出 | 已交付 |
| 多模块工程 | 23 个独立 module，由 `fago-server/go.work` 组成 workspace | 已交付 |
| 后台任务 | worker 独立启动和退出，运行定时任务、站内通知，以及 Event 或 Redis Streams | 已交付 |
| 消息队列 | Event 与 Redis Streams 已有正式运行入口和积压观测。RabbitMQ、Kafka、RocketMQ 尚未接入 | 建设中 |
| 达梦数据库 | 适配器与开发实例探针存在，默认 API 不装配，版本矩阵未认证 | 试验 |
| 其他商业库 | Oracle、SQL Server 等只有探针或目标，没有完整运行时 | 规划 |

### 工作流

`fago-server/modules/fago-workflow-core` 与 `fago-server/modules/fago-workflow-resource` 已在仓库中。内核只有有界持久化试验，不是可交付的审批产品。

| 功能 | 描述 | 进度 |
| --- | --- | --- |
| 流程内核 | 定义、执行、持久化的有界试验；不依赖系统模块，也不绑定某一种资源 | 试验 |
| 审批操作 | 会签、或签、候选人策略、驳回、转办 | 规划 |
| 在线设计 | 动态表单与流程设计器 | 规划 |
| 资源审批 | 文件、文档和业务资源走同一套流程 | 规划 |

### 业务扩展

支付、商城、CRM、ERP、MES、WMS、财务，以及 AI、IoT、IM、报表，留待平台底座稳定后按具体业务扩展。本仓库没有这些模块。

## 技术栈

### 模块

| 模块 | 说明 | 进度 |
| --- | --- | --- |
| `modules/fago-contracts` | 窄契约，不依赖业务 | 已交付 |
| `modules/fago-framework` | 配置、日志、错误、HTTP、事务端口 | 已交付 |
| `modules/fago-security` | 敏感字段脱敏与生产 JWE；可选 SM2/SM4 套件 | 已交付 |
| `modules/fago-tenancy` | 租户上下文与隔离 | 已交付 |
| `modules/fago-identity` | 租户、平台、会员与服务身份，会话、认证模式和 OIDC | 已交付 |
| `modules/fago-system` | 用户、部门、岗位、角色、菜单、数据范围、安全策略与审计查询 | 已交付 |
| `modules/fago-infra` | 字典、参数、文件、通知与定时任务 | 已交付 |
| `modules/fago-codegen` | 元数据读取与受限模板代码生成 | 已交付 |
| `modules/fago-messaging` | outbox、inbox 与可靠消息契约 | 已交付 |
| `modules/fago-ops` | 显式初始化与运维用例，供 CLI 装配 | 已交付 |
| `modules/fago-workflow-core` | 纯 Go 工作流内核，有界试验 | 试验 |
| `modules/fago-workflow-resource` | 文件、文档和业务资源接入流程的端口 | 规划 |
| `adapters/database/fago-mysql` | MySQL 方言 | 已交付 |
| `adapters/database/fago-postgres` | PostgreSQL 方言 | 已交付 |
| `adapters/database/fago-dm` | 达梦方言，默认 API 不引入 | 试验 |
| `adapters/messaging/fago-event` | Event 通知传输 | 已交付 |
| `adapters/messaging/fago-redis` | Redis Streams 传输 | 已交付 |
| `adapters/storage/fago-local` | 预建绝对目录；API 与 worker 必须共用该目录 | 已交付 |
| `adapters/storage/fago-s3` | 显式 endpoint 的通用 S3 适配 | 已交付 |
| `fago-migrations` | MySQL、PostgreSQL、达梦迁移脚本 | 已交付 |
| `apps/fago-server` | API、worker 的装配入口 | 已交付 |
| `apps/fago-cli` | 迁移、初始化、密钥与开发工具；二进制名 `fago-cli` | 已交付 |
| `poc/fago-database` | 商业数据库探针，默认 API 不引入这些驱动 | 试验 |
| `poc/fago-oidc` | 早期 OIDC 试验；正式运行面在身份模块与 API | 试验 |

路径相对于 `fago-server/`。目录和 module path 使用 `fago-` 前缀，Go 包名使用 `fago` 前缀。`api`、`worker`、`cli` 三个入口保留 `package main`。

### 框架

| 框架 | 说明 | 版本 |
| --- | --- | --- |
| [Go](https://go.dev/) | 语言与工具链 | 1.27.3 |
| [Gin](https://github.com/gin-gonic/gin) | HTTP 框架 | 1.12.0 |
| [GORM](https://gorm.io/) | 数据访问 | 1.31.1 |
| [go-redis](https://github.com/redis/go-redis) | Redis 客户端 | 9.16.0 |
| MySQL | 已装配的业务库 | 由 `APP_DATABASE_DRIVER=mysql` 选择 |
| PostgreSQL | 已装配的业务库 | 由 `APP_DATABASE_DRIVER=postgres` 选择 |
| Vben 5 | 前端，应用为 web-antd | `fago-vben5/`，包管理器 pnpm 11.16.0 |

## 启动

在 `fago-server/` 执行。数据库和 Redis 需要事先可用。连接串、Redis 口令和初始管理员口令只通过环境变量提供，口令不写进命令参数。

开发配置 `configs/config.development.yaml` 已将 Cookie 设为 `development-http`，Origin 为 `http://127.0.0.1:5174`。该 profile 只允许非生产 loopback。生产推荐 HTTPS 和浏览器实际看到的精确 Origin；未使用 HTTPS 时 API 启动给出警告。生产 API 还要提供外部 RSA 私钥。字段见 [configs/README.md](fago-server/configs/README.md)。

```bash
cd fago-server

export APP_ENV=development
export APP_DATABASE_DRIVER=mysql
export APP_DATABASE_DSN='user:password@tcp(127.0.0.1:3306)/fago?charset=utf8mb4&parseTime=true&loc=UTC'
export APP_REDIS_ADDR=127.0.0.1:6379
export APP_HTTP_ADDR=127.0.0.1:8081

go run ./apps/fago-cli/cmd/fago-cli migrate

export BOOTSTRAP_TENANT_CODE=example
export BOOTSTRAP_TENANT_NAME=示例企业
export BOOTSTRAP_USERNAME=admin
read -r -s BOOTSTRAP_PASSWORD
export BOOTSTRAP_PASSWORD
go run ./apps/fago-cli/cmd/fago-cli bootstrap
unset BOOTSTRAP_PASSWORD

go run ./apps/fago-server/cmd/api
```

口令至少 14 个字符、不超过 72 字节。默认 `BOOTSTRAP_REALM=admin`，创建的是租户身份。平台身份必须另设 `BOOTSTRAP_REALM=platform`，并单独提供口令。初始化会要求首次登录改密。

PostgreSQL 将 `APP_DATABASE_DRIVER` 设为 `postgres`，并换用对应 DSN。worker 使用同一套环境变量，在 `fago-server/` 执行：

```bash
go run ./apps/fago-server/cmd/worker
```

前端在 `fago-vben5/`。Node.js 使用 22.18 或 24.12，包管理器为 pnpm 11.16.0。开发页 Origin 使用 `http://127.0.0.1:5174`，并把 `/api` 转发到上面的 API。外层编排仓库可改用 `scripts/web.sh`。

迁移中途失败会停下并留下 dirty 标记，需要先核对库中的实际对象，再决定补偿或在可丢弃的空库上重建。直接清掉标记后继续执行，会让版本记录和真实结构对不上。

初始租户只能创建一次。重复执行 bootstrap 会失败，并保留已有凭证。

健康检查：

* `GET /api/health/live`
* `GET /api/health/ready`

依赖不可用时，就绪检查返回 HTTP 503 和业务码 `503001`，响应带 `requestId`。