echo-admin

echo-admin

echo-admin 是一个 module-first 的 Go 中后台基础框架。它提供登录认证、管理员管理、角色权限、菜单管理、API Token、系统配置、数据字典、文件上传和分类、操作日志、登录日志和系统错误日志，为后续业务模块提供统一后台管理能力。

项目后端使用 Go 1.26、Echo v5、Casbin 和 samber/do。前端位于 web/，使用 Umi Max、React、Ant Design 和 ProComponents。

架构边界

• business module：业务模块，位于 internal/modules/<module>。
• platform：平台运行时代码，位于 internal/platform。
• capability：可复用基础设施能力，例如 MySQL、Redis、MongoDB、tracing、logging。
• composition root：启动装配层，位于 internal/boot。

核心目录：

.
├── cmd/                         # CLI 入口，默认读取 configs/config.toml
├── configs/                     # 静态配置示例和配置说明
├── internal/boot/               # composition root，负责装配资源、模块和路由
├── internal/modules/auth/       # 登录会话、当前用户和授权判断
├── internal/modules/identity/   # 管理员管理
├── internal/modules/access/     # 角色权限和菜单管理
├── internal/modules/apitoken/    # API Token 管理和 token 认证
├── internal/modules/settings/   # 系统配置和数据字典
├── internal/modules/fileasset/  # 文件上传元数据和分类
├── internal/modules/audit/      # 操作日志、登录日志和系统错误日志
├── internal/platform/           # HTTP runtime、配置、错误、请求响应、基础设施能力
├── web/                         # 前端中后台应用
├── k8s/                         # Kubernetes 示例
├── docker-compose.yaml          # 本地开发 Compose
├── Dockerfile                   # runtime image
└── Makefile                     # 构建、测试、验证命令

不要把本项目改回 service/biz/data 分层心智。业务路由只在 internal/boot 通过 NewModule、Provide、Route 显式装配，internal/platform/server 不 import 业务模块。

快速开始

后端依赖 MySQL 存储。先启动本地 MySQL：

docker compose up mysql

再启动 API：

export ECHO_ADMIN_MYSQL_PASSWORD="echo_admin_dev_password"
go run main.go --config configs/config.toml

默认监听 :9322。基础检查：

curl http://127.0.0.1:9322/api/health
curl http://127.0.0.1:9322/api/info
curl http://127.0.0.1:9322/api/ready
curl http://127.0.0.1:9322/api/capabilities

首次启动空库后，普通管理接口会保持未初始化状态。浏览器后台会先进入 /setup，由初始化页创建权限目录、API 目录、基础菜单、super_admin Root Role、系统配置、状态字典和首个管理员。这个管理员由初始化表单填写，并自动绑定最高权限 Root Role；初始化成功后再跳转到登录页。

打开后台: http://127.0.0.1:8000/setup
填写: username / display_name / email(可选) / password / site_name(可选)

super_admin 是根角色，默认拥有全部权限、全部基础菜单、全部 API、全部按钮、全部数据角色和默认入口 /dashboard。管理员可以拥有多个角色；浏览器登录使用服务端 Login Session 和 HttpOnly cookie，当前生效角色保存在本次登录会话中。切换角色后后端更新当前登录会话，前端菜单、按钮权限和数据权限随 /api/auth/me 刷新。退出登录只撤销当前登录会话，logout-others 可撤销同一管理员的其他登录会话。

前端：

cd web
npm install
npm run dev

前端 dev server 默认把 /api 代理到 http://127.0.0.1:9322；如需连接其他后端，设置 ECHO_ADMIN_WEB_API_TARGET。生产部署按同源 /api 访问，浏览器登录后通过 cookie 携带登录会话，unsafe method 会自动带 X-CSRF-Token。机器客户端继续使用 X-API-Token。

配置

默认配置文件是 configs/config.toml。配置支持 TOML、YAML、JSON，未知配置字段会导致启动失败。环境变量前缀是 ECHO_ADMIN_。

浏览器后台默认使用 Login Session；服务端只把 opaque session token 写入 HttpOnly cookie，MySQL 只保存 SHA-256 哈希。状态变更请求使用 Echo CSRF middleware，前端从 csrf_token cookie 读取并发送 X-CSRF-Token。生产 HTTPS 部署应开启 secure cookie：

[http]
secure_cookies = true

数据库 host、port、database、username 和连接池等非敏感拓扑配置写在配置文件的 [mysql] 中；MySQL 密码可以写在私有配置文件，也可以由 ECHO_ADMIN_MYSQL_PASSWORD 注入。首次管理员密码不在静态配置中维护，由 /setup 初始化页提交，长度必须是 8 到 72 个字符。

可选 capability 默认关闭：

• redis.enabled=false
• mongodb.enabled=false
• tracing.enabled=false
• http.cors.enabled=false

MySQL 是后台基础能力的必需存储，示例配置默认 mysql.enabled=true。Redis、MongoDB、tracing 等可选资源启用后会进入 /api/ready 和 /api/capabilities。上传文件默认保存到 admin.upload_dir，本地示例值是 uploads。

完整配置说明见 configs/README.md。

本地 Compose

默认 docker compose up 启动 API 和 MySQL，公开端口默认绑定 127.0.0.1：

docker compose up

Redis、MongoDB 和 Jaeger 在 resources profile 下：

cp env.example .env
docker compose --profile resources up

.env 只给 Docker Compose 做本地开发端口和凭据替换；应用本身读取真实进程环境变量，不会自动加载 .env 文件。

资源服务使用 Compose 命名卷保存本地开发数据。需要重置本地资源状态时，显式运行 docker compose down -v。

Foundation Modules

后台基础能力按边界拆成多个 business module：

internal/modules/auth/           # 登录认证、当前用户和权限判断
internal/modules/identity/       # 管理员生命周期
internal/modules/access/         # 角色、权限和菜单
internal/modules/apitoken/       # API Token 管理和 token 认证
internal/modules/settings/       # 系统配置和数据字典
internal/modules/fileasset/      # 文件上传元数据和分类
internal/modules/audit/          # 操作日志、登录日志和系统错误日志

运行期只使用 MySQL adapter。各模块的 usecase 定义自己的 store interface，internal/boot 从已配置的 *gorm.DB 创建 concrete store，并负责跨模块装配，例如 auth 通过自己的小接口读取 identity/access，并通过 boot bridge 写入 audit。

授权判断基于 Casbin RBAC：管理员映射为 user:<id>，角色映射为 role:<code>，权限 token 必须是 resource:action，并在授权时映射为 Casbin 的 {subject, object, action}。当前生效角色决定本次请求的权限集合，已分配但未激活的其他角色不会参与授权。

auth 模块提供登录、当前用户、当前用户资料更新、角色切换、当前用户改密码、服务端退出登录和权限判断。浏览器登录态是 MySQL 持久化的 Login Session；cookie 中只保存 opaque token，表中只保存 token 哈希、当前角色、idle 过期时间、绝对过期时间和撤销信息。登录会话校验发生在 server middleware：过期、撤销、管理员不可用或角色不可用都会按未授权处理。当前用户改密码只撤销其他会话并保留当前会话；管理员被禁用、删除或被重置密码会撤销该管理员全部会话。API Token 是独立的机器客户端认证路径，不复用浏览器 cookie。

access 模块提供权限目录、API 目录、角色树、数据权限、菜单管理和菜单按钮管理。权限目录、API 目录、菜单 meta 和菜单按钮会持久化到 MySQL，便于初始化检查和后台审计；后台私有 API 会由 boot 安装的统一 route 授权 middleware 拦截，按 Echo 注册路由的 method/path 查找 API 目录，并要求普通角色持有对应 api_ids。super_admin 默认拥有全部权限、全部基础菜单、全部菜单按钮、全部数据角色和全部初始化 API，新增 API 记录不会把根角色锁在门外，但普通角色必须显式分配对应 API 后才能访问该接口。角色通过 parent_id 形成委派树：super_admin 可以管理全部角色；普通角色只能查看自己和下级角色，只能把自己的下级角色分配给管理员，并且不能授予自己没有的权限、菜单、API、菜单按钮或数据角色。data_role_ids 是当前角色可见的管理员数据范围，管理员列表按这些角色过滤；管理员创建、更新和删除仍按可分配角色边界校验。基础菜单按“工作台、组织权限、系统管理、资源管理、运维审计”组织，菜单项通过 permission token 控制可见性，API 记录上的 permission 字段作为目录和前端授权元数据保留，HTTP handler 不再重复声明 permission token。菜单记录同时保存 hidden、component、keep_alive、default_menu、close_tab、active_name 和 transition_type 等 gin-vue-admin 风格路由元信息。前端静态路由只注册页面，最终菜单显示以后端 /api/auth/me 返回的菜单为准。

settings 模块提供系统配置、系统参数、数据字典和版本管理。系统配置支持创建、更新、删除，启动种子配置 site_name 不允许从后台删除。系统参数提供 gin-vue-admin 风格的可分页参数表，支持名称/键筛选、按 ID 或 key 查询、创建、更新、单条删除和批量删除。数据字典支持字典项树形父子关系、扩展值、层级路径、防循环父级调整和父项删除保护。版本管理保存可审计的发布记录，版本号唯一，包含版本名称、说明和发布时间；支持详情读取、JSON 下载、单条删除、批量删除、选择菜单/API/字典导出版本包，以及导入版本包恢复菜单、API 和字典，创建、导出、导入、更新、删除都会写操作日志。

apitoken 模块提供 API Token 列表、创建、更新、作废和请求认证。创建 token 时可指定目标管理员、目标角色和 1-365 天有效期；普通角色只能给自己当前身份签发，super_admin 可以给已启用且持有目标角色的管理员签发。明文只返回一次，MySQL 只保存 SHA-256 哈希和短前缀；后续列表和更新接口不会回显明文或哈希。服务端接受 X-API-Token 请求头，验证成功后把 token 绑定的管理员和角色写入 request context，后续仍由同一套 route 授权 middleware 校验 API 目录和角色 api_ids。停用或过期 token 会被拒绝，成功使用会更新 last_used_at；删除操作会作废 token，不物理删除记录。

fileasset 模块提供本地上传、外部 URL 元数据登记、文件重命名、文件删除和分类树管理。文件可以按分类筛选，上传和导入 URL 时可选择分类；删除分类只会把该分类下的文件归到未分类，不会删除文件资产。本地上传文件通过 /api/uploads/* 读取时同样经过统一 API route grant 拦截。

audit 模块保存操作日志、登录日志和系统错误日志，并支持单条和批量删除。系统错误日志由统一 HTTP 错误边界记录，只记录内部错误和 panic 恢复后的 5xx 响应；普通 4xx 业务错误不会写入系统错误表。错误记录包含安全响应码、请求路径、请求 ID、用户 ID 和诊断 detail，供超管在日志页排查；超管可以把系统错误标记为已处理、记录处理备注，也可以取消处理状态。

HTTP adapter 只做请求解析、validator 校验、DTO 转换、调用 usecase、统一响应。核心业务规则放在 domain 和 usecase。

HTTP API

系统路由：

后台基础路由：

新业务模块

新增业务模块时，按这个顺序写：

1. internal/modules/<module>/domain
2. internal/modules/<module>/usecase
3. internal/modules/<module>/adapters/mysql
4. internal/modules/<module>/http
5. internal/boot/business.go
6. 行为测试

职责边界：

• domain 放领域对象、构造函数、领域错误和不可变业务规则。
• usecase 放输入输出、业务流程和 usecase-owned outbound interface。
• adapters/<adapter> 实现 usecase 定义的 interface。
• http 复用 internal/platform/server/httpreq 和 internal/platform/server/httpresp。
• internal/boot 负责选择 adapter、装配依赖、挂载路由。

跨模块依赖不要直接 import 对方 store 或 adapter。由消费方 usecase 定义小接口，再在 internal/boot 写 bridge。

验证

后端：

make test
make lint
make build
make verify

前端：

cd web
npm run lint
npm run test
npm run build

修改 Go 依赖后必须运行 go mod tidy。前端构建产物 web/dist、Umi 生成目录和 Utoo cache 不提交。

进一步阅读

• AGENTS.md：仓库级开发约束。
• configs/README.md：配置项和环境变量覆盖规则。
• internal/boot/README.md：composition root 和模块装配说明。
• internal/platform/server/README.md：HTTP runtime 边界说明。
• web/README.md：前端开发说明。