01. 部署与配置¶
1. 环境要求¶
| 依赖 | 建议版本 | 必需性 | 说明 |
|---|---|---|---|
| Go | 1.25+ | 必需 | 后端构建和运行。 |
| Node.js | 20+ | 前端构建必需 | www 使用 Vite 7 和 React 19。 |
| MySQL/MariaDB | MySQL 5.7+ / MariaDB 10.3+ | 必需 | 主业务数据库。 |
| Redis | 6.0+ | 推荐 | refresh token 存储，不可用时降级到内存。 |
| MinIO | 兼容 minio-go/v7 | 推荐 | 上传、资源、固件、通信音频。 |
| Keycloak | 可选 | 可选 | SSO 登录。 |
2. 创建数据库¶
CREATE DATABASE draarl CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
建议为 DraARL 单独创建数据库账号，并只授予该数据库所需权限。
3. 配置文件¶
默认配置文件为 udphub.yaml。如果命令行未指定 -c，程序会在可执行文件所在目录查找 udphub.yaml。
复制模板：
cp udphub.yaml.example udphub.yaml
Windows：
Copy-Item udphub.yaml.example udphub.yaml
4. 核心配置说明¶
4.1 System¶
| 字段 | 说明 |
|---|---|
Host |
UDP 监听地址，空字符串表示所有网卡。 |
Port |
UDP 服务端口，示例为 60050。 |
LogPath |
日志文件路径，空字符串表示不输出到文件。 |
IPfile |
IP 地址库路径，默认 ./udphub.ipdb。 |
ProxyProtocol |
可配置 v2，用于从 frp 等代理获取真实客户端 IP。 |
4.2 Database¶
| 字段 | 说明 |
|---|---|
Host / Port |
MySQL 地址。 |
User / Password |
数据库账号。 |
DBName |
数据库名。 |
Charset / Collate |
默认 utf8mb4 / utf8mb4_unicode_ci。 |
MaxOpenConns |
最大打开连接数，默认 25。 |
MaxIdleConns |
最大空闲连接数，默认 5。 |
MaxLifetime |
连接最大存活时间，单位秒，默认 300。 |
4.3 Redis¶
Redis 用于 refresh token 存储。程序启动时优先连接 Redis；如果连接失败，会降级到内存存储。内存模式可以运行，但服务重启后 refresh token 状态会丢失，生产环境建议配置 Redis。
| 字段 | 说明 |
|---|---|
Host / Port |
Redis 地址。 |
Password |
Redis 密码。 |
DB |
Redis 数据库编号。 |
Prefix |
Key 前缀，默认 draarl。 |
DialTimeoutSec / ReadTimeoutSec / WriteTimeoutSec |
连接和读写超时。 |
PoolSize |
连接池大小。 |
4.4 Web¶
| 字段 | 说明 |
|---|---|
Host |
HTTP 监听地址，空字符串表示所有网卡。 |
Port |
HTTP/API/WebSocket 服务端口。 |
FrontendURL |
前端对外地址，用于 SSO 回调重定向，也会加入 Origin 白名单。 |
AllowedOrigins |
允许访问 API 和 WebSocket 的页面来源。生产环境必须正确配置。 |
FrontendCDN.Enabled |
发布模式下是否将嵌入前端静态资源同步到 MinIO。 |
FrontendCDN.ObjectPrefix |
前端资源在 MinIO 中的对象前缀，默认 frontend。 |
生产环境注意：
- 后端会校验
Origin/Referer。 - release 构建下如果没有可解析的
FrontendURL或AllowedOrigins，程序会启动失败。 - API 网关会拒绝 URL query 中出现 token 类参数，例如
token、access_token、refresh_token、jwt。
4.5 Keycloak¶
Keycloak 为可选 SSO 配置。启用后，登录页会显示 SSO 登录入口。
| 字段 | 说明 |
|---|---|
Enabled |
是否启用 SSO。 |
Name |
前端显示名称。 |
BaseURL |
Keycloak 服务器地址。 |
Realm |
Realm 名称。 |
ClientID / ClientSecret |
客户端配置。 |
RedirectURI |
后端 /api/sso/callback 回调地址。 |
4.6 MinIO¶
| 字段 | 说明 |
|---|---|
Endpoint |
MinIO 地址。 |
AccessKey / SecretKey |
凭据。 |
UseSSL |
是否使用 HTTPS。 |
Bucket |
默认桶名。 |
BasePath |
对外访问基础路径，用于生成文件 URL。 |
涉及头像、操作证、资源中心、固件、通信音频时，建议确保 MinIO 可用。
4.7 JWT 与设备认证¶
| 字段 | 说明 |
|---|---|
JWT.Secret |
JWT 签名密钥，最少 32 字符。不符合要求时程序会自动生成并写入配置文件。 |
DeviceAuth.AESKey |
设备密码加密密钥，必须为 16、24 或 32 字节。不符合要求时程序会自动生成并写入配置文件。 |
5. 后端运行¶
go mod download
go build -o draarl ./cmd/udphub
./draarl -c udphub.yaml
常用启动参数：
| 参数 | 说明 |
|---|---|
-c <path> |
指定配置文件。 |
-v |
打印版本信息。 |
-p json |
打印关键配置。 |
-auto-migrate |
执行数据库自动迁移。 |
-reset-admin-pass <password> |
重置管理员密码。 |
6. 数据库迁移¶
程序只有在显式传入 -auto-migrate 时才执行 GORM 自动迁移：
./draarl -c udphub.yaml -auto-migrate
自动迁移会：
- 清理部分重复或孤儿数据。
- 自动创建/更新核心表结构。
- 建立级联外键约束。
- 确保
users.callsign、devices(owner_id, ssid)等唯一索引。 - 删除
group_members历史设备级字段。
生产环境首次升级前建议备份数据库。
7. 管理员初始化¶
首次启动时，如果数据库中不存在名为 admin 的用户，程序会创建默认管理员并在日志输出随机密码。该用户：
- 用户名：
admin - 角色：
admin - 审核状态：已通过
重置管理员密码：
./draarl -c udphub.yaml -reset-admin-pass "NewPassword123"
8. 前端开发运行¶
cd www
npm install
npm run dev
当前 vite.config.ts 中开发服务器端口为 9001，并将 /api 代理到 http://localhost:9002。如果后端 Web 端口不是 9002，需要调整开发环境的 API 地址或代理配置。
9. 发布构建¶
Unix/macOS/Linux：
./build.sh v1.2.3
Windows：
.\build.bat v1.2.3
发布脚本流程：
- 清理旧产物。
- 构建
www/dist。 - 将前端产物复制到
internal/server/web/dist。 - 使用
-tags=embed构建后端，将前端嵌入二进制。 - 清理临时嵌入目录。
发布模式下，Go 二进制可同时提供 API 和前端页面。非 embed 构建只提供 API，访问前端路由会返回 frontend not embedded, build with -tags=embed。
10. 相关 API¶
| Method | Path | Auth | 说明 |
|---|---|---|---|
| GET | /api/platform/info |
Public | 平台信息。 |
| GET | /api/platform/totalstats |
Public | 平台统计。 |
| GET | /api/config/public |
Public | 公开站点配置。 |
| GET | /api/config/category/:category |
JWT | 分类配置读取。 |
| GET | /api/config/all |
Admin | 全部配置。 |