SunAdmin 开发文档

主题

🔧 环境配置 ​

SunAdmin 的配置分为三层：Laravel .env 管部署环境变量，configs 数据库表管后台可维护的业务配置，前端 .env.* 文件管编译时配置。本页聚焦前两层和前端环境文件。

🧑‍🔧 Laravel .env ​

常见配置项：

配置说明建议
APP_NAME应用名称默认可用 SunAdmin
APP_ENV环境本地 local，生产 production
APP_KEY加密密钥必须通过 php artisan key:generate 生成
APP_DEBUG调试开关生产必须为 false
APP_URL应用 URL用于命令行、上传 URL 兜底，也是支付回调地址生成依据
DB_*数据库连接安装向导或手工配置
CACHE_STORE缓存驱动开发可用 file，生产建议 redis
QUEUE_CONNECTION队列驱动开发 sync/database，生产建议 redis
LOG_CHANNEL日志通道默认 daily，按日生成日志文件
LOG_STACKstack 日志通道组合默认 daily
LOG_DAILY_DAYS按日日志保留天数默认可用 14
SESSION_DRIVER会话驱动按部署环境选择
FILESYSTEM_DISKLaravel 默认磁盘SunAdmin 业务上传还会读取后台存储配置

生产环境修改 .env 后要重新执行：

bash
php artisan optimize:clear
php artisan config:cache

日志默认按天写入 storage/logs，保留 14 天。日志查看、堆栈显示、清空和按日删除说明见 日志与审计。

🔩 业务配置表 ​

后端业务配置通过 configs 表维护，业务代码读取配置优先使用全局 sysConfig()，避免到处写较长的服务调用。

读取单值：

php
$value = sysConfig('storage', 'default', 'local');
$value = sysConfig('storage.default', 'local');

读取分组：

php
$storage = sysConfig('storage');

读取多个分组：

php
$configs = sysConfig(['basics', 'storage', 'ai']);

写入配置有两种方式：

php
use Modules\System\Application\Services\Config\GroupedConfigService;

// 新增或完整覆盖：需要传入配置名称、类型等元信息
$groupedConfigService->setValue('basics', 'sys_status', 1, '站点状态', 'switch');

// 只改值：配置项已存在时，只更新 value 字段，其余元信息不变
$groupedConfigService->updateValue('basics', 'sys_status', 0);

日常业务中保存后台表单配置通常用 updateValue()，只有首次创建配置项或需要同时修改类型、选项等元信息时才用 setValue()。

配置写入后会自动清理当前分组缓存，并递增公开配置的版本号（前端通过版本号判断是否需要重新拉取配置）。

🗺️ config/sunadmin.php ​

项目级业务配置集中在：

text
config/sunadmin.php

主要分组：

分组说明
version框架版本号，与 composer.json 同步
admin_captcha后台验证码类型
site_status用户端站点状态缓存与关闭文案
config_cache配置分组缓存
dict_cache字典缓存
hot_cache公共配置、装修页、语言包热点缓存
cache_versions版本号缓存 key
rate_limits登录、短信、AI、上传限流（含 admin_upload、api_upload 两个上传限流子项）
locks短信、AI 等业务锁时间
async.ai_usageAI 用量异步记录
list全局分页默认值和最大值
upload上传类型、扩展名、大小限制
pay支付基础能力的驱动、回调处理器与业务处理器注册
modules模块命令配置（command_user 控制 Linux 下重新执行的用户身份）
install安装锁文件路径

后台“应用接入 / 支付接入”中的 pay.default_driver 用于选择当前默认支付驱动。业务模块未显式传入 driver 时，支付基础能力会使用该配置发起支付。支付模块自己的商户号、密钥、证书等参数也在支付接入页按驱动标签维护。

钱包提现手续费属于 Wallet 模块配置，安装钱包模块后由“钱包管理 / 钱包设置”维护：

text
wallet.withdrawal_fee_type
wallet.withdrawal_fee

🧑‍🔬 Admin 环境文件 ​

开发环境配置

text
frontend/admin/.env.development

生产环境配置

text
frontend/admin/.env.production

关键配置同下方 uni-app 章节说明。

📌 uni-app 环境文件 ​

开发环境配置

text
frontend/uniapp/.env.development

生产环境配置

text
frontend/uniapp/.env.production

关键配置：

ts
// H5 与后端同域部署时可使用相对根路径
VITE_APP_BASE_URL='/'

// 小程序和 App 需要填写可访问的完整接口域名
VITE_APP_BASE_URL=https://example.com/

📌 请求接口说明 ​

VITE_APP_BASE_URL 只配置域名或根路径，不需要填写接口前缀，如 adminapi、api。业务前缀由请求封装统一拼接。

API 模块遵循标准：模块名/example/index，比如后台的文章列表接口：/system/article/list/index

ts
export function articleList(params?: Record<string, any>) {
  return request.get({ url: '/system/article/list/index', params })
}

实际请求是：https://example.com/adminapi/system/article/list/index

🗂️ 配置变更检查 ​

场景需要同步检查操作
修改 .env清理并重建 Laravel 配置缓存php artisan optimize:clear && php artisan config:cache
修改 config/sunadmin.php确认生产环境配置缓存已刷新php artisan config:cache
后台保存配置分组缓存和公开配置版本号自动失效无需手动操作
修改上传限制同步测试 Admin 上传和 uni-app 上传—
修改前端接口域名重新启动 dev server 或重新构建—
小程序/App 切换域名确认平台合法域名也已配置—