深浅模式
初始化向导
首次部署时，通过浏览器打开 /setup 完成数据库、Redis、域名、密钥等 一次性 配置。向导完成后会写入 config.yaml、自动建表，之后该地址将不可用。
访问条件
| 条件 | 说明 |
|---|---|
| 地址 | http://服务器IP:8080/setup 或 https://你的域名/setup |
| 服务已启动 | 宝塔 进程守护 中 lingmeng 已运行，或等价守护进程 |
| 未完成安装 | config.yaml 中 app.setup_completed 为 false |
HTTPS
生产环境强烈建议 先配置 SSL 再访问 setup。非 HTTPS 且非 localhost 时页面会提示风险。
向导步骤总览
| 步骤 | 名称 | 主要内容 |
|---|---|---|
| 00 | 站点授权 | 拉取 license（部分部署可跳过） |
| 01 | 应用与网络 | 项目名、端口、网站地址、跨域 |
| 02 | 数据存储 | MySQL、Redis、Meilisearch、Gorse 等 |
| 03 | 安全与密钥 | JWT 密钥、加密密钥、权限策略 |
| 04 | 确认安装 | 测试连接 → 写入配置 → 建表 |
步骤 00：站点授权
| 字段 | 说明 |
|---|---|
| 授权编号 | 形如 lic_xxx，从授权方获取 |
| 拉取密钥 | 授权站实例详情中复制 |
| 拉取授权文件 | 下载 license 到服务器 |
若检测到官方授权域名，此步可能自动跳过，直接进入配置。
步骤 01：应用与网络
应用基础
| 字段 | 必填 | 说明 | 常见错误 |
|---|---|---|---|
| 项目名称 | 推荐 | 后台与日志显示名 | — |
| 网站端口 | 必填 | 默认 8080，Go 进程监听端口 | 与 Nginx 反代端口不一致 |
| 网站地址 | 必填 | 完整 URL，如 https://campus.example.com | 须与后续微信回调、H5 域名 完全一致；填错导致登录/支付回调失败 |
页面会 实时校验 当前访问域名与填写地址是否匹配。
跨域访问
| 字段 | 说明 |
|---|---|
| 允许访问的前端地址 | CORS 白名单，每行一个 Origin |
| 允许携带凭证 | 一般开启 |
示例（生产）：
text
https://campus.example.com
https://www.campus.example.com若有独立 H5 域名、管理后台域名，都要列入。
步骤 02：数据存储
数据库 MySQL（必填）
| 字段 | 默认/示例 | 说明 |
|---|---|---|
| 服务器地址 | 127.0.0.1 | Docker 部署勿填 localhost 若 MySQL 在别的容器 |
| 端口 | 3306 | — |
| 用户名 | — | 建议专用账号，非 root |
| 密码 | — | — |
| 数据库名 | 如 lingmengv2 | 须提前创建空库，或账号有建库权限 |
| 字符集 | utf8mb4 | 必须 utf8mb4，否则 emoji 乱码 |
缓存 Redis（必填）
| 字段 | 说明 |
|---|---|
| 地址 / 端口 | 如 127.0.0.1:6379 |
| 密码 | 无密码可留空 |
| 库编号 | 默认 0 |
| 缓存前缀 | 如 lingmeng，多站点同 Redis 时 必须不同 |
Meilisearch 搜索（可选）
| 字段 | 说明 |
|---|---|
| 启用 | 未部署 Docker 搜索服务则 关闭 |
| 服务地址 | 默认 http://127.0.0.1:7700 |
| API Key | 与 docker-compose 中 Master Key 一致 |
→ 见 可选基础设施
Gorse 推荐（可选）
| 字段 | 说明 |
|---|---|
| 启用 | 未部署则关闭 |
| 服务地址 | 默认 http://127.0.0.1:8087 |
| API Key | 与部署配置一致 |
步骤 03：安全与密钥
| 字段 | 必填 | 说明 |
|---|---|---|
| 登录密钥 | 必填 | JWT 签名，点 生成登录密钥 随机即可 |
| 登录有效期（小时） | 推荐 | 如 168（7 天） |
| 数据加密密钥 | 可选 | 留空自动生成；生产留空后勿丢 config.yaml |
| 文件签名密钥 | 可选 | 私有文件访问签名 |
| 管理员兼容旧版权限 | 新站 关闭 | 开启会导致未配 Grant 的管理员权限过宽 |
密钥备份
安装完成后 备份 config.yaml（含所有密钥）。丢失后用户登录态、加密数据可能无法恢复。
步骤 04：确认安装
- 点击 测试连接 — 验证 MySQL、Redis、已启用的 Meilisearch/Gorse
- 全部通过后点 确认安装
- 等待建表进度条完成
- 记录页面显示的 管理员账号密码（默认可能为
admin/admin123） - 按提示重启 Go 服务
安装成功后 /setup 不可再访问。
安装完成后必做清单
| # | 操作 | 路径 |
|---|---|---|
| 1 | 修改管理员密码 | 管理后台登录 → 个人设置 |
| 2 | 完善网站信息 | 系统设置 → 网站信息 |
| 3 | 配置文件存储 | 系统配置 → 文件存储 |
| 4 | 配置微信（若需要） | 系统配置 → 微信小程序/公众号 |
| 5 | 搭建首页 UI | 从零搭建首页 |
| 6 | 生产核对 | 上线检查清单 |
高级设置（「更多设置」折叠区）
安装时一般 不必展开。以下为运维调优项，安装后也可直接改 config.yaml：
| 分区 | 典型字段 |
|---|---|
| 数据库连接池 | 最大连接数、连接存活时间 |
| 日志 | 目录、JSON 格式、慢请求阈值 |
| HTTP 服务 | 读/写超时、Brotli 压缩 |
| 全局限流 | IP/用户维度 QPS |
| 定时任务 | 是否启用调度 |
| Prometheus | 监控指标开关 |
新站点保持默认即可，遇性能问题再调整。
常见问题
向导打不开
- 服务未启动或防火墙未放行端口
setup_completed已为true（已安装过）
测试连接失败
- MySQL：库不存在、密码错、远程未授权
- Redis：密码错、bind 127.0.0.1 导致容器不通
想重新安装
- 生产 不建议。须备份数据库 → 改
setup_completed: false→ 清库或新库 → 再走向导