Goravel Admin

简体中文

English

简体中文

English

主题

开源定位与生产配置 ​

1. 适用 / 不适用 ​

适合 ​

  • 企业内部后台、运营后台、管理中台
  • Goravel + Vue / React 的二次开发脚手架
  • 需要 RBAC、菜单、日志、导出、代码生成器的管理端
  • 中小规模业务扩展（用户、订单、支付管理等示例能力可选用）

不适合 ​

  • 金融级交易核心、强一致支付中台（支付模块为管理端 + 网关示例）
  • 超大规模、多区域、强 SLA 的商业 SaaS 产品中台
  • 未做运维规划就开启「分表 + ES + 多队列」当生产核心

演示站账号仅用于体验；生产请改默认管理员密码，并配置独立密钥。

1.1 支付模块边界 ​

能力状态
支付方式 CRUD、支付记录列表/详情/导出✅ 可用
为订单创建支付单 POST /api/admin/payments + 可选 initiate✅ 参考下单
Mock 网关 下单 / 查询 / 回调 → ApplyPaidResult（支付+订单幂等已支付）✅ 本地可跑通，见 支付参考
微信 / 支付宝下单客户端调用（gopay）⚠️ 示例代码，需自备商户配置
微信 / 支付宝查询与回调验签⚠️ 返回 payment_gateway_not_implemented（501）；验签后复用 ApplyPaidResult
新渠道扩展✅ RegisterPaymentGateway + 通用 notify/{type}，见 支付参考 §6
退款 API / 原路退❌ 未提供（余额日志里的 refund 类型仅统计用）

演示可开 MODULE_PAYMENTS_ENABLED=true；公网未自研网关时保持关闭或仅用 mock。

2. 模块分层：核心 vs 进阶 ​

核心（默认可跑） ​

能力说明
认证授权JWT、RBAC、菜单权限
系统管理管理员、角色、部门、字典、配置
日志操作日志、登录日志、系统日志
基础导出列表导出（小数据可同步；异步导出见进阶）
代码生成器本地/开发环境使用；生产请限权或关闭

最小依赖： MySQL（或兼容库）+ 可运行的 Go 服务。
本地开发可用 QUEUE_CONNECTION=sync、CACHE_STORE=memory（不推荐生产）。

进阶（可选，按需开启） ​

模块何时需要相关配置 / 文档
Redis 缓存 / 队列生产导出、异步任务、限流与锁CACHE_STORE、QUEUE_CONNECTION
订单 / 支付分表数据量大、按月归档分表迁移、SHARDING_*
Elasticsearch订单检索、全文检索ELASTICSEARCH_*、ES Worker
多队列驱动Kafka / RabbitMQ / NSQ / Redis Stream.env.example 队列段
OpenTelemetryJaeger / Grafana 等统一观测OTEL_*、Telemetry 文档
AI / pprof / Swagger开发与排障生产默认关闭或限权
一户一库多租户大商户隔离（默认关闭）TENANCY_DRIVER=database、平台 /api/platform、见 多租户

AI（可选）： 「代码生成器 → AI 辅助」与 AI 实验室（文本 / 视觉 / 图片 / 语音）。未配置 AI_API_KEY（或 OPENAI_API_KEY）时相关菜单自动隐藏。实验室限流：AI_LAB_RATE_LIMIT_PER_MINUTE / AI_LAB_RATE_LIMIT_PER_DAY。AI_ENABLED=false 可关闭。详见 .env.example。

模块开关 ​

变量默认说明
MODULE_ORDERS_ENABLEDtrue关闭后隐藏订单菜单并拒绝订单 API
MODULE_PAYMENTS_ENABLEDfalse管理端支付菜单与 API；公网默认建议关闭
PAYMENT_GATEWAYS_ENABLED（空）启用渠道白名单，如 wechat,alipay；空则全部已注册驱动
APP_ENABLE_DEV_TOOLfalse生产需显式 true 才开放开发工具。表单演示：local/development/test 默认可见；代码生成器：仅 local/development 默认可见（test 默认隐藏）

登录 Info 与 menus/tree 会按开关过滤菜单；前端 userStore.config 同步 orders_enabled / payments_enabled / payment_gateways。菜单可见性以服务端为准；前端模块布尔字段目前为信息字段（非路由守卫），支付类型下拉以 payment_gateways 为准。

数据权限（租户内行级） ​

挂在角色上（roles.data_scope），多角色取最宽；super-admin 始终全部数据。与一户一库租户隔离正交：先租户连接，再行级过滤。

值含义
1全部数据
2自定义部门（role_department）
3本部门
4本部门及以下
5仅本人

已接入列表：管理员（department_id）、文章 / 附件 / 导出记录（admin_id）。服务入口：ApplyDataScope / ResolveAdminDataScope。

3. 最小生产配置 ​

适用于：后台管理为主、暂不分表、暂不用 ES。

ini
APP_ENV=production
APP_DEBUG=false
APP_KEY=          # 必填：go run . artisan key:generate
JWT_SECRET=       # 必填：强随机字符串

LOG_CHANNEL=stack
LOG_LEVEL=info

DB_CONNECTION=mysql
# ... 生产库连接 ...

CACHE_STORE=redis
QUEUE_CONNECTION=redis
QUEUE_CONCURRENT=2
QUEUE_TRIES=5

# DOMAINS_ADMIN=admin.example.com

# 生产默认关闭
SWAGGER_ENABLED=false
# APP_DISABLED_RUNNERS=  # 不要误关 queue:*

上线检查（最小）：

  1. migrate 成功，db:seed 后修改默认 admin 密码
  2. Redis 可用，Web 进程与 Queue Worker 常驻
  3. HTTPS + 反向代理
  4. 关闭或限权：Swagger、pprof、代码生成器
  5. 日志磁盘与备份策略就绪
  6. 使用 .env.production.example 起步，勿直接用 docker-compose.yml 默认口令上生产

部署细节见 生产清单（健康检查 /health /ready、告警与上线清单）、编译与部署、Docker 生产部署。

资源归属（管理端） ​

  • 导出：下载 / 进度 SSE / 删除仅本人或配置的 admin.super_admin_id
  • 附件：私有文件读/写同归属规则；公开附件（is_public=1）已登录管理员可读，改删仍需所有者或超管
  • 支付：mock 可跑通下单/回调/订单同步；微信/支付宝查询与回调验签为 payment_gateway_not_implemented（501），见 支付参考

4. 进阶配置 ​

按需叠加：

4.1 异步导出 / 长任务 ​

ini
QUEUE_CONNECTION=redis
QUEUE_LONG_RUNNING_CONCURRENT=1
# Worker 需消费 long-running 队列（见 bootstrap runners）

4.2 分表 ​

ini
# SHARDING_TIME_SUFFIX_LAYOUT=200601
# SHARDING_MAX_TIME_RANGE_MONTHS=3
# SHARDING_ID_LOOKUP_SCAN_MONTHS=6
# SHARDING_USER_BALANCE_LOGS_SHARDS=4

并配置定时任务创建未来分表（见分表文档）。

4.3 搜索引擎（Elasticsearch / Meilisearch） ​

详见 搜索。

ini
SEARCH_DRIVER=elasticsearch   # 或 meilisearch
SEARCH_ENABLED=true
SEARCH_SYNC_ORDERS=true
SEARCH_QUEUE=search
SEARCH_SYNC_WORKER=auto
# SEARCH_OUTBOX_ENABLED=true
ELASTICSEARCH_URLS=http://127.0.0.1:9200
# MEILISEARCH_HOST=http://127.0.0.1:7700

需要搜索集群 + queue-search Worker。Outbox 积压可用 go run . artisan search:retry-outbox 补偿。初始化：search:init-orders-index，全量：search:sync-orders。其他业务索引用 search.RegisterDefinition 扩展（见 搜索）。

4.4 OpenTelemetry ​

ini
# OTEL_TRACES_EXPORTER=otlptrace
# OTEL_METRICS_EXPORTER=otlpmetric
# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:4318

未配置 exporter 时框架会自动禁用 goravel:telemetry runner。

5. 相关文档 ​

文档说明
快速开始本机开发或 Docker 一键跑通
编译与部署编译与部署
测试指南测试指南
分表迁移分表
错误码错误码
系统架构架构
多租户一户一库 / PG Schema 多租户（TENANCY_DRIVER=database）
搜索Elasticsearch / Meilisearch 切换、订单同步、文章扩展
生产清单生产上线清单、/health /ready、告警
SaaS 核对清单中小 SaaS 上线核对清单
支付参考订单/支付参考链路、mock 与微信支付宝扩展点