English | 简体中文
后端服务。Go 1.25 + Gin + database/sql + SQLite(modernc.org/sqlite,纯 Go 无 CGO)。
模块名 mini-ruoyi。数据库后端只有 SQLite 一种,没有多方言抽象。
- Go 1.25 或更高(
go.mod声明go 1.25,启用了GOTOOLCHAIN=auto时会自动下载对应工具链) - 不需要 CGO,不需要 SQLite 命令行工具
cd server
# 直接跑(若当前目录或二进制同级目录没有 web/,会自动降级为纯 API 模式)
go run ./cmd/server
# 验证
curl localhost:8080/healthz
# {"code":200,"msg":"ok","data":{"status":"up"}}从仓库根目录构建完整产物(含前端):
make build && make run # 二进制与前端产物落在 bin/启动时会自动执行未应用的迁移,并创建 data.db(若不存在)。
仓库自带的 data.db 是已经初始化好的库:迁移记录齐全(0002–0013 全部已应用),
基础数据是 admin 账号(密码 admin123)、内置管理员角色、13 个菜单与 3 个任务,开箱即用。
库里还留着一些开发期产生的记录——若干会话、登录日志、操作日志、任务执行记录,以及一个 test 角色。
这是刻意保留的演示数据:打开后台时列表页就有内容可看,不用先自己造一遍。
server/ 启动后端时 database.path 就是它),
你登录、操作一次就会继续往里写。想要一个「刚跑完迁移」的干净基线就跑一次 make db-clean
(它顺带清零登录失败计数——开发时把 admin 连错 5 次被锁住,就用这个解锁)。
最终方案是从 migrations/ + 种子 SQL 重新生成(见 ../docs/architecture.md §8),
那时这个库会被移除,也就不再需要这条注意事项。
优先级:环境变量 > 配置文件 > 内置默认值。
cp config/config.example.yaml config/config.yaml # 可选,不改也能跑config.yaml 在 .gitignore 里;可提交的样例是 config/config.example.yaml,
每一项都带注释。用 APP_CONFIG 可以指定别的路径。
| 变量 | 默认值 | 配置文件里的位置 |
|---|---|---|
APP_CONFIG |
config/config.yaml |
—(配置文件路径本身) |
APP_ADDR |
:8080 |
server.addr |
APP_ENV |
prod |
server.env |
APP_SECURE_COOKIE |
false |
server.secure_cookie |
APP_TRUSTED_PROXIES |
空 | server.trusted_proxies(逗号分隔) |
APP_RATE_LIMIT_RPS |
20 |
server.rate_limit.rps |
APP_RATE_LIMIT_BURST |
40 |
server.rate_limit.burst |
APP_DB_PATH |
data.db |
database.path |
APP_WEB_DIR |
自动查找 | web.dir |
APP_UPLOAD_DIR |
uploads |
upload.dir |
APP_UPLOAD_MAX_MB |
20 |
upload.max_mb |
APP_UPLOAD_QUOTA_MB |
512 |
upload.quota_mb |
APP_LOG_RETENTION_DAYS |
30 |
log.retention_days |
配置错了会拒绝启动:配置文件里出现未知字段、环境变量取值非法、 以及「配额小于单文件上限」这类自相矛盾的组合,都会在启动时失败并指出具体位置。 静默退回默认值的话,用户只会觉得「我明明配了怎么不生效」。
启动日志里有一行生效配置摘要,路径都是绝对路径。
全部在 /api/v1 下。完整契约(信封、错误键、删除确认)见
../docs/architecture.md。
启动时会打印当前端点分类:
已注册 44 个 API 端点(公开 1 / 仅登录 4 / 需权限 39)
认证方式:登录后服务端下发 mr_session cookie(HttpOnly / SameSite=Lax)。
除登录外,所有写操作都必须带 X-CSRF-Token 头,值取自登录响应或 /auth/me 的
csrf_token 字段。
| 方法 | 路径 | 权限码 | 说明 |
|---|---|---|---|
| POST | /auth/login |
— (公开) | 登录,下发 cookie 与 CSRF 令牌 |
| GET | /auth/me |
仅登录 | 当前用户 + 权限码 + 菜单树 + CSRF 令牌 |
| POST | /auth/logout |
仅登录 | 登出,服务端立即删除会话 |
| PUT | /profile |
仅登录 | 改自己的昵称/手机/邮箱。改不了状态——否则等于允许自解禁 |
| PUT | /profile/password |
仅登录 | 改自己的密码。需提供旧密码,只踢掉其他会话 |
| GET | /menus |
system:menu:list |
完整菜单树(含未启用项) |
| GET | /menus/:id |
system:menu:list |
|
| POST | /menus |
system:menu:add |
|
| PUT | /menus/:id |
system:menu:edit |
|
| DELETE | /menus/:id |
system:menu:delete |
支持 ?cascade=true |
| GET | /roles |
system:role:list |
分页 |
| GET | /roles/:id |
system:role:list |
|
| GET | /roles/:id/grants |
system:role:list |
菜单授权 + 权限码 |
| POST | /roles |
system:role:add |
|
| PUT | /roles/:id |
system:role:edit |
|
| PUT | /roles/:id/grants |
system:role:edit |
覆盖式重设授权 |
| DELETE | /roles/:id |
system:role:delete |
支持 ?cascade=true |
| GET | /roles/export |
system:role:list |
按当前筛选导出 CSV(不导出授权:那是另一份关系表) |
| GET | /perms |
system:perm:list |
权限清单,按资源分组,含每个权限码保护的接口(来自启动时装配的路由表,不查库) |
| GET | /users |
system:user:list |
分页,支持 username / nickname / mobile / status / role_id 筛选 |
| GET | /users/:id |
system:user:list |
含 role_ids |
| POST | /users |
system:user:add |
|
| PUT | /users/:id |
system:user:edit |
用户名不可变 |
| PUT | /users/:id/roles |
system:user:edit |
|
| PUT | /users/:id/password |
system:user:resetPwd |
重置后立即踢掉该用户全部会话 |
| DELETE | /users/:id |
system:user:delete |
|
| GET | /users/export |
system:user:list |
按当前筛选导出 CSV;超过 10000 行报错,不静默截断 |
| POST | /users/import |
system:user:add |
导入 CSV(multipart:file + password);一行不合格则整批不写,?dry_run=1 只校验 |
| GET | /system |
monitor:system:list |
本机 CPU / 内存 / 磁盘 / Go 进程状态 |
| GET | /sessions |
monitor:session:list |
在线会话(未过期的),最近活跃在前 |
| DELETE | /sessions/:hash |
monitor:session:kick |
踢掉一条会话,对方下次请求即失效 |
| DELETE | /users/:id/sessions |
monitor:session:kick |
强退某用户全部会话 |
| GET | /login-logs |
monitor:loginlog:list |
登录日志,支持 username / status / start / end 筛选 |
| GET | /login-logs/export |
monitor:loginlog:list |
按当前筛选导出 CSV(reason 是 i18n 键,不是译文) |
| GET | /oper-logs |
monitor:operlog:list |
操作日志,支持 username / method / path / start / end 筛选 |
| GET | /oper-logs/export |
monitor:operlog:list |
按当前筛选导出 CSV(比列表多一列 user_agent) |
| GET | /files |
tool:file:list |
文件列表,响应还带容量用量 |
| GET | /files/:id/download |
tool:file:list |
下载。强制保存,不做内联预览 |
| POST | /files |
tool:file:upload |
multipart 上传,字段名 file,可带 group |
| DELETE | /files/:id |
tool:file:delete |
删除记录与磁盘文件 |
| GET | /jobs |
tool:job:list |
定时任务(来自代码注册表) |
| PUT | /jobs/:key |
tool:job:edit |
改 cron / 启停,立即重新调度 |
| POST | /jobs/:key/run |
tool:job:run |
立即执行一次(异步,结果刷新列表看) |
| GET | /jobs/:key/logs |
tool:job:list |
该任务的执行历史(分页,按时间倒序) |
| GET | /healthz |
— (公开) | 探活,会真实 Ping 数据库 |
| 改自己的 | 改他人的 | |
|---|---|---|
| 资料 | PUT /profile(仅登录) |
PUT /users/:id(要 system:user:edit) |
| 密码 | PUT /profile/password(仅登录,需旧密码) |
PUT /users/:id/password(要 system:user:resetPwd) |
改自己的那两个不要任何权限码:初始密码是管理员设的,如果改自己的密码也要
system:user:resetPwd,那一个只授了只读权限的账号连自己的密码都改不了。
它们走的是 self 路由(仅校验登录)。
两处差异是刻意的:
- 改自己密码必须验旧密码——否则一个被盗用的会话就能直接改掉密码把机主锁在外面
- 改自己密码只踢其他会话,当前这条保留。改完立刻把自己登出,用户会以为改失败了
curl -c cookie.txt -X POST localhost:8080/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"admin123"}'{"code":200,"msg":"ok","data":{
"user":{"id":1,"username":"admin","nickname":"管理员", ...},
"is_admin":true,
"perms":["system:menu:add", "..."],
"csrf_token":"Xce5DgS3...",
"expires_at":"2026-10-04T08:45:15Z",
"menus":[{"title_key":"menu.system","children":[...]}]
}}内置管理员(角色 code='admin')的 perms 会返回全部已声明的权限码,
所以前端只需要一种判断:perms.includes(code)。它的权限是隐式的、不落库,
见 ../docs/schema.md §8.2。
不带 ?cascade=true 时,若资源有子数据会返回 409 并携带影响面:
curl -b cookie.txt -X DELETE localhost:8080/api/v1/menus/1{"code":409,"msg":"error.hasDependents",
"data":{"child_menus":3,"affected_roles":2}}前端收到它不是弹错误提示,而是弹确认框并把数字展示出来;用户确认后重发
DELETE .../menus/1?cascade=true。各资源的影响面字段见
../docs/architecture.md §3.4。
失败响应的 msg 是 i18n 键而非文案,文案由前端渲染。
| HTTP | msg |
|---|---|
| 400 | error.validationFailed / error.malformedBody / error.invalidId / error.invalidDate / error.invalidParent / error.invalidPermCode |
| 401 | error.unauthorized / error.badCredentials |
| 403 | error.forbidden / error.protected / error.accountDisabled / error.cannotDeleteSelf / error.cannotKickSelf / error.csrfInvalid |
| 404 | error.notFound |
| 409 | error.hasDependents / error.lastAdmin / error.duplicate |
| 400 | error.invalidJobCron / error.invalidFile / error.wrongOldPassword / error.passwordTooLong / error.importNoFile / error.importMissingColumns / error.importTooManyRows / error.exportTooManyRows |
| 413 | error.bodyTooLarge / error.fileTooLarge / error.quotaExceeded |
| 429 | error.tooManyRequests(按 IP 限流) / error.accountLocked(连续登录失败 5 次后锁 10 分钟,锁期内密码正确也进不去) |
| 500 | error.internal |
| 503 | error.serviceUnavailable |
| 404 | error.frontendDisabled(纯 API 模式下访问非 API 路径,提示前端未部署) |
后端不会返回 error.network 和 error.backendUnreachable——这两个是前端产生的
(前者表示请求没有任何东西应答,后者表示有响应但不是本服务的信封格式)。
内置限制:请求体上限 1 MiB,按 IP 限流 20 rps(突发 40),单账号连续登录失败 5 次锁 10 分钟
(auth.MaxLoginFailures / auth.LoginLockDuration,管理员重置密码可立即解锁)。
stdout 日志是 logfmt 结构化格式(log/slog):访问日志带 method / path / status /
duration_ms / request_id,≥500 记 ERROR、其余记 INFO。同一次请求的 request_id 会回写到响应头
X-Request-Id,上游传来的合法值会被沿用、非法值重新生成(防日志注入)。
审计日志批量落库,最多有 2 秒延迟(原因见 ../docs/architecture.md §5.2)。
保留期由 APP_LOG_RETENTION_DAYS 控制,默认 30 天。
-
在
internal/repository/migrations/新建<序号>_<描述>.sql,序号零填充 4 位:internal/repository/migrations/0002_init_users.sql -
直接写 SQL,一个文件可以有多条语句:
CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT NOT NULL UNIQUE, ... ); CREATE INDEX idx_users_username ON users(username);
-
重启服务即自动应用。
规则:
- 只向前补齐,不支持回滚。 改错了就再加一个修复迁移
- 每个文件在单个事务内执行,DDL 失败不会留下半截结构
- 执行记录写入
schema_migrations,已应用的会跳过。重复启动是幂等的 - 迁移文件通过
//go:embed打包进二进制,因此必须与代码一起发布,不能靠运维单独拷 SQL
迁移只能追加:版本记录在 schema_migrations,只执行没跑过的文件,不重建、不覆盖已有数据,
否则老库(表已存在、可能没有任何迁移记录)升级会失败。参考用例 TestMigrateOnLegacyDatabase(旧库带数据、无迁移记录)与
TestMigrateDetectsMissingTables(记录说跑过、表却不在)。
PRAGMA 通过 DSN 的 _pragma 参数下发,不要改成 db.Exec("PRAGMA ...")——
那是连接级设置,db.Exec 只会配置连接池里的某一条连接,其余连接仍是默认值
(foreign_keys=0、busy_timeout=0)。详见
../docs/architecture-server.md。
repository/sqlite_test.go 有对应回归用例,改动连接配置后必须让它通过。
go test ./... # 全部
go test ./internal/repository/ -v # 单包
go test ./... -run TestNewDBConfiguresPragmas # 单例
gofmt -l . && go vet ./... # 提交前用例覆盖范围见 ../docs/architecture-server.md 的「测试」一节。
cmd/server/main.go 启动、依赖组装、优雅关闭
internal/config/ 环境变量 → Config
internal/domain/ 实体 + 领域错误(最内层)
internal/httpx/ 响应信封、错误键、错误→状态码映射
internal/reqid/ 请求 ID(X-Request-Id)生成与校验,供日志关联
internal/repository/ 连接、迁移、单表 SQL
internal/service/ 业务规则、分页归一化
internal/handler/ HTTP 适配:绑定、校验、响应
internal/middleware/ 日志、安全头、限流、请求体上限、缓存头
internal/httpserver/ 路由装配、静态资源托管 + SPA 兜底
依赖方向严格单向:handler 只允许 import repository 来组装列表筛选条件
(Filter 家族),不得写 SQL、不得做业务判断。详见
../docs/architecture-server.md。
新增一个资源的完整步骤(12 步)也写在那份文档里。
- 列表导出:用户、角色、操作日志、登录日志都已支持(用户还支持 CSV 导入);菜单、文件、任务、会话、API 清单还没有
devices 示例资源已移除:在 fail-closed 的权限模型下,它要么污染生产权限清单,
要么留下一个无权限的 CRUD 接口,两者都不该出现在正式版本里。