开源定位与生产配置

1. 适用 / 不适用

适合

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

不适合

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

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

1.1 支付模块边界

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

公网请用 PAYMENT_GATEWAYS_ENABLED 限制网关，并勿给无关角色支付权限。

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

核心能力

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

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

进阶（可选，按需开启）

模块	何时需要	相关配置 / 文档
Redis 缓存 / 队列	生产导出、异步任务、限流与锁	`CACHE_STORE`、`QUEUE_CONNECTION`
订单 / 支付分表	数据量大、按月归档	分表迁移、`SHARDING_*`
调度演示（活动窗口 / 订单超时）	二次开发样板；非生产营销中台	调度演示、`/api/schedule-demo`
Elasticsearch	订单检索、全文检索	`ELASTICSEARCH_*`、ES Worker
OpenTelemetry	Jaeger / 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。

模块开关

变量	默认	说明
`PAYMENT_GATEWAYS_ENABLED`	（空）	启用渠道白名单，如 `wechat,alipay`；空 / `` / `all` = 全部已注册。生产建议显式白名单*；新渠道见支付参考 §6
`APP_ENABLE_DEV_TOOL`	`false`	生产需显式 `true` 才开放开发工具。表单演示：`local/development/test` 默认可见；代码生成器：仅 `local/development` 默认可见（`test` 默认隐藏）

数据权限（租户内行级）

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

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

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

业务字段脱敏（列表 / 导出）

对配置的敏感字段在列表与导出中掩码；详情 Show 保持明文，避免编辑表单把掩码写回库。绕过角色（默认 super-admin）看明文。

**按租户 / 站点：**后台 → 系统管理 → 配置管理 → 字段脱敏，写入当前库 configs（group=desensitize）。TENANCY_DRIVER=database 时每个租户库独立——只有需要脱敏的租户打开即可；未配置时回退 .env 的 DESENSITIZE_ENABLED。

配置	默认	说明
`DESENSITIZE_ENABLED`	`true`	进程默认（`config/desensitize.go`）
`configs.desensitize.enabled`	（env）	租户/单站覆盖
bypass slug（env 或 DB）	`super-admin`	逗号分隔
modules	`user` / `admin` 的 `phone`、`email`	策略：`phone` / `email` / `hide` / `keep_ends`

已接入：用户列表与用户导出、管理员列表与管理员同步导出。Update 会忽略已含 * 的掩码值。

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=  # Worker 机勿设 queue-*；API 多机见生产清单 §4.1

上线检查（最小）：

migrate 成功，db:seed 后修改默认 admin 密码
Redis 可用；Web 与 Queue Worker 常驻（多机分角色配置见生产清单 §4.1）
HTTPS + 反向代理
关闭或限权：Swagger、pprof、代码生成器
日志磁盘与备份策略就绪
使用 .env.production.example 起步，勿直接用 docker-compose.yml 默认口令上生产

部署细节见生产清单（健康检查 /health /ready、任务中心/导入权限、队列积压告警、上线清单）、编译与部署、Docker 生产部署。升级含任务中心时务必按生产清单 §1.1 核对 export/TaskCenter 菜单与 import.* 权限。

资源归属（管理端）

导出：下载 / 进度 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 与微信支付宝扩展点

开源定位与生产配置 ​

1. 适用 / 不适用 ​

适合 ​

不适合 ​

1.1 支付模块边界 ​

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

核心能力 ​

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

模块开关 ​

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

业务字段脱敏（列表 / 导出） ​

3. 最小生产配置 ​

资源归属（管理端） ​

4. 进阶配置 ​

4.1 异步导出 / 长任务 ​

4.2 分表 ​

4.3 搜索引擎（Elasticsearch / Meilisearch） ​

4.4 OpenTelemetry ​

5. 相关文档 ​