195 lines
12 KiB
Plaintext
195 lines
12 KiB
Plaintext
================================================================================
|
||
EasyGoAdmin 后端开发者文档 · 10 配置参考与部署
|
||
================================================================================
|
||
配置文件：manifest/config/config.yaml（唯一运行时配置）
|
||
环境变量覆盖：GF_GENV_ 前缀 + 下划线路径，如 GF_GENV_DATABASE_DEFAULT_LINK
|
||
|
||
--------------------------------------------------------------------------------
|
||
1. server 服务端
|
||
--------------------------------------------------------------------------------
|
||
address: ":8000" 监听地址
|
||
openapiPath: "/api.json" OpenAPI 文档（gf 原生生成，bind.go 补注册闭包路由）
|
||
swaggerPath: "" Swagger UI 路径置空——内置页依赖境外 CDN，
|
||
改为本地托管 resource/swagger/（/swagger 入口）
|
||
dumpRouterMap: false 启动打印路由表
|
||
errorStack: true 响应携带错误堆栈（生产可关）
|
||
graceful: true 优雅重启
|
||
|
||
--------------------------------------------------------------------------------
|
||
2. logger 日志
|
||
--------------------------------------------------------------------------------
|
||
level: "all" stdout: true path: "log"
|
||
|
||
--------------------------------------------------------------------------------
|
||
3. database 数据库（五方言可切换）
|
||
--------------------------------------------------------------------------------
|
||
default:
|
||
type: "mysql" 运行时驱动：mysql/pgsql/mssql/oracle/sqlite
|
||
link: "mysql:root:root@tcp(127.0.0.1:3306)/easygoadmin.goframe.elevue?charset=utf8mb4&parseTime=true&loc=Local"
|
||
debug: false SQL 调试日志（调试期开，生产关）
|
||
其他方言示例（config 内注释）：
|
||
pgsql: "pgsql:user:password@tcp(127.0.0.1:5432)/easygoadmin?sslmode=disable"
|
||
mssql: "mssql:sa:Password1@tcp(127.0.0.1:1433)/easygoadmin?encrypt=disable"
|
||
oracle: "oracle:user:password@tcp(127.0.0.1:1521)/XE"
|
||
sqlite: "sqlite::@file(easygoadmin.db)"
|
||
切换只需改 type+link（五驱动已在 main.go 全部注册）。
|
||
注意库名含点（easygoadmin.goframe.elevue），DDL 引用需反引号。
|
||
|
||
--------------------------------------------------------------------------------
|
||
4. redis 缓存
|
||
--------------------------------------------------------------------------------
|
||
default: address 127.0.0.1:6379 db 0 pass "" idle 10 maxActive 50 timeout 300
|
||
用途：JWT 黑名单、验证码、字典缓存、身份/租户摘要缓存、限流计数、
|
||
在线用户 zset、任务执行锁。
|
||
不可用时自动降级进程内存（utility/cache.Init + 运行期自动切换）；
|
||
降级影响：多实例不共享（限流/锁/在线用户退化单机语义）。
|
||
|
||
--------------------------------------------------------------------------------
|
||
5. jwt 双令牌
|
||
--------------------------------------------------------------------------------
|
||
secret: 签名密钥（生产必须修改！）
|
||
issuer: "easygoadmin"
|
||
accessTokenExpire: 7200 访问令牌（秒）
|
||
refreshTokenExpire: 604800 刷新令牌（说明项）
|
||
※ 运行时刷新令牌有效期代码读取 jwt.refreshExpire，未配置回退 168h（=604800s，
|
||
与 refreshTokenExpire 同值）。如需自定义请配置 jwt.refreshExpire。
|
||
|
||
--------------------------------------------------------------------------------
|
||
6. captcha 图形验证码
|
||
--------------------------------------------------------------------------------
|
||
expire: 300 bypassCode: "618618"（万能验证码，仅开发调试，生产留空！）
|
||
length: 6（4~8） chars: 排除 0O/1lI 的字符集
|
||
fontPath: resource/static/fonts/Vera.ttf（缺失降级 SVG）
|
||
imageWidth/Height/FontSize/noiseLines/noiseDots：渲染参数
|
||
|
||
--------------------------------------------------------------------------------
|
||
7. rateLimit 限流
|
||
--------------------------------------------------------------------------------
|
||
enable: true limit: 120 windowSeconds: 60 authLimit: 10
|
||
语义：每窗口每 IP 每路径；authLimit 仅对 /api/login、/api/captcha、
|
||
/api/oauth2/token；limit=0 关闭普通限流；仅 /api 前缀参与。
|
||
|
||
--------------------------------------------------------------------------------
|
||
8. operationLog 操作日志
|
||
--------------------------------------------------------------------------------
|
||
enable: true 总开关
|
||
logQuery: true 是否记录查询类（logType=query）操作
|
||
|
||
--------------------------------------------------------------------------------
|
||
9. job 定时任务
|
||
--------------------------------------------------------------------------------
|
||
logRetentionDays: 90 三张日志表保留天数（LogClean 消费，任务参数
|
||
retentionDays 可覆盖）
|
||
|
||
--------------------------------------------------------------------------------
|
||
10. tenant 租户
|
||
--------------------------------------------------------------------------------
|
||
defaultId: 1 超管新增租户级数据时的默认归属租户（显式指定时从显式值）
|
||
|
||
--------------------------------------------------------------------------------
|
||
11. app 应用
|
||
--------------------------------------------------------------------------------
|
||
timezone: "Asia/Shanghai"
|
||
demo: false 演示模式：true 时写操作一律拒绝（登录等公开接口放行）
|
||
errorMsg: true 返回详细错误信息（生产建议 false）
|
||
|
||
--------------------------------------------------------------------------------
|
||
12. api
|
||
--------------------------------------------------------------------------------
|
||
camelSnakeConvert: true 全链路驼峰，恒开
|
||
proxyIps: "127.0.0.1,::1,101.226.0.0/15,..." 受信代理（逗号分隔，支持 CIDR）；
|
||
仅直连来源命中时才信任 X-Forwarded-For / X-Real-IP（限流计数、日志 IP、
|
||
归属地解析均依赖此处准确性）
|
||
|
||
--------------------------------------------------------------------------------
|
||
13. cors
|
||
--------------------------------------------------------------------------------
|
||
allowOrigin: "*" 空或 * 用框架内置策略；具体来源显式回显 + 预检 204
|
||
|
||
--------------------------------------------------------------------------------
|
||
14. file 文件上传
|
||
--------------------------------------------------------------------------------
|
||
uploadDir: 上传物理根目录（绝对路径，按环境调整）
|
||
domainUrl: 文件访问域名（如 http://file.goframe.elevue；为空用 /upload/ 相对路径）
|
||
tempDir: "temp"
|
||
imageExt: gif,jpg,jpeg,png,bmp,webp,svg
|
||
fileExt: 上述 + doc/docx/xls/xlsx/ppt/pptx/pdf/zip/rar/txt/csv/mp3/mp4/sql/js/css
|
||
maxSize: 10（MB）
|
||
tempExpireDays: 7 临时目录保留天数（0=不清理；CleanTemp 每日 03:30 执行）
|
||
|
||
--------------------------------------------------------------------------------
|
||
15. generator 代码生成器
|
||
--------------------------------------------------------------------------------
|
||
parentMenuId: 189 新模块菜单挂载的父级菜单 ID
|
||
overwrite: false 覆盖开关：true 生成即覆盖已存在文件；
|
||
false/缺省 = 缺失补生成、存在跳过
|
||
|
||
--------------------------------------------------------------------------------
|
||
16. ip2region 归属地
|
||
--------------------------------------------------------------------------------
|
||
path: "manifest/data/ip2region.xdb" IPv4 xdb 文件
|
||
|
||
--------------------------------------------------------------------------------
|
||
17. gf gen 配置（hack/config.yaml，开发工具链）
|
||
--------------------------------------------------------------------------------
|
||
gfcli.gen.dao:
|
||
link / removePrefix goframe_ / group default / jsonCase CamelLower /
|
||
descriptionTag true / overwriteDao false /
|
||
tplDaoIndexPath hack/tpl/dao_index.tpl（自定义：挂全局钩子 + Ctx 覆写）/
|
||
path internal、daoPath dao、doPath model/do、entityPath model/entity
|
||
gfcli.gen.service:
|
||
srcFolder internal/logic → dstFolder internal/service；
|
||
clear: false（gf v2.10.3 Windows 下 clear 逻辑路径分隔符不匹配会误删，
|
||
故关闭；且 service 本就手维护，勿整体运行）
|
||
|
||
--------------------------------------------------------------------------------
|
||
18. 部署要点
|
||
--------------------------------------------------------------------------------
|
||
18.1 部署拓扑图
|
||
|
||
┌────────────┐
|
||
│ 浏览器/ui │
|
||
└─────┬──────┘
|
||
│ /api/*（JWT）
|
||
反向代理(可选,需列入 api.proxyIps)
|
||
nginx/… ──────────────▶┌──────────────────────────────┐
|
||
│ admin-server :8000 │
|
||
│ 中间件链 + Bind + logic │
|
||
│ gcron（job daemon + 03:30 │
|
||
│ 上传清理） │
|
||
└───┬──────────┬──────────┬─────┘
|
||
│ │ │
|
||
┌─────────▼──┐ ┌─────▼─────┐ ┌──▼──────────────┐
|
||
│ MySQL/PG… │ │ Redis │ │ 磁盘 │
|
||
│ goframe_* │ │ 缓存/锁/ │ │ file.uploadDir │
|
||
│ 25 张表 │ │ 在线/限流 │ │ manifest/data/xdb│
|
||
└────────────┘ └───────────┘ │ log/ │
|
||
└─────────────────┘
|
||
多实例：应用可横向扩展；Redis 保证 限流计数/任务执行锁/在线用户 跨实例一致
|
||
（Redis 降级内存时以上全部退化为单机语义）
|
||
|
||
构建：go build -o bin/admin-server.exe main.go（Windows）；Linux 同理去 .exe
|
||
启动：./bin/admin-server.exe（默认 :8000）
|
||
重启（本机）：见 document/启动命令.txt——先按端口找 PID taskkill，再编译启动
|
||
依赖检查清单：
|
||
1) MySQL 可连（database.default.link）
|
||
2) Redis 可连（不可用自动降级但多实例语义受损）
|
||
3) manifest/data/ip2region.xdb 存在
|
||
4) file.uploadDir 目录存在且可写；file.domainUrl 可对外访问
|
||
5) jwt.secret 修改为环境专属值；captcha.bypassCode 生产留空；app.demo=false；
|
||
app.errorMsg=false（生产）
|
||
6) generator.parentMenuId 按环境菜单树确认
|
||
静态资源：SetServerRoot("resource") 对外暴露 resource/（含 /upload、/swagger、字体）
|
||
健康检查：GET /api/health → {"code":0,"data":{"status":"up"}}（免登录，不限流）
|
||
API 文档：GET /swagger（本地 Redoc 页）；GET /api.json（OpenAPI JSON）
|
||
日志：控制台 + log/ 目录（logger.path）
|
||
|
||
--------------------------------------------------------------------------------
|
||
19. 质量与回归
|
||
--------------------------------------------------------------------------------
|
||
静态检查：go vet ./... && gofmt -l .
|
||
测试：go test ./...（命令见 Makefile test 目标）
|
||
接口回归基线：hack/golden/ 与 hack/after* 目录存放接口响应黄金样本
|
||
（如 article_page.json、level_list.json 等），用于比对接口行为回归；
|
||
比对时注意分页等动态参数需带录制参数（如 pageSize=3）对齐。
|