# icutool-ark-backend

**Repository Path**: plusboy/icutool-ark-backend

## Basic Information

- **Project Name**: icutool-ark-backend
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# icutool-ark-backend

> 方舟：生存进化（ARK: Survival Ascended）开服管理后端，提供物资分发、玩家档案、VIP 策略与 RCON 运维等一站式能力。

## 目录
- [项目简介](#项目简介)
- [核心能力](#核心能力)
- [技术架构](#技术架构)
- [目录速览](#目录速览)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [配置详解](#配置详解)
- [数据库与种子数据](#数据库与种子数据)
- [API 概览](#api-概览)
- [RCON 运维能力](#rcon-运维能力)
- [缓存策略](#缓存策略)
- [安全提示](#安全提示)
- [Roadmap](#roadmap)
- [贡献指南](#贡献指南)
- [English Quick Overview](#english-quick-overview)
- [License](#license)

## 项目简介
icutool-ark-backend 是一个使用 Go 1.21+ 编写的 Web API，面向私服/社区服主理人，帮助自动化以下场景：

- 从海量道具 Blueprint 中检索、分页、下发武器/恐龙。
- 维护玩家账号、SteamID、金币、VIP 等数据资产。
- 通过 RCON 实时广播运营活动、推送礼包，或查看在线状态。
- 管理 VIP 每日奖励与金币发放日志，方便审计。
- 根据登录 IP 自动标记地理位置，辅助风控。

2026-03-16 起仓库已完成 Java 版本迁移，当前主分支随代码自动执行 GORM AutoMigrate，并提供 `api.md` 作为详细接口文档。

## 核心能力
- **分层架构**：`handler → service → dao → model` 清晰解耦，方便替换任意存储或协议实现。
- **RCON 客户端增强**：自动重连、分包粘包处理、命令模板（`giveitemtoplayer` / `spawnTamedDino` / `broadcast` 等）。
- **Token 认证**：登录使用 Redis 缓存 Token（24h），支持 Header / Query 双通道，并在登录时写入 IP 所在地。
- **Redis 缓存**：对道具、分组、类别等热点数据做 30 分钟～1 小时缓存，命中失败自动回源并回写。
- **玩家资产**：支持分页查询、更新玩家档案，维护 VIP 配置与金币发放日志，便于 GM 流程。
- **可观测性**：全局接入 logrus，统一 API 响应格式，自带 `/api/v1/ping` 健康检查与 `/api/v1/rcon/test` 联通性自检。

## 技术架构
### 运行流程
1. `cmd/server/main.go` 读取 `-env` 参数（dev/home/prod），通过 `internal/config` + Viper 加载 `configs/config.<env>.yaml`。
2. `pkg/db` 初始化 MySQL、Redis 连接；若配置了 `data/ip2region_*.xdb` 则加载 IP2Region 索引。
3. GORM 自动迁移 `HotEventData、ArkItem、ItemGroup、KindConfig、ArkPlayerAccount、ArkVipLevelConfig、ArkCoinRewardLog` 等表。
4. `internal/router` 注入中间件（CORS、Auth），构建 DAO/Service/Handler 并注册 `/api/v1` 路由。
5. Gin Engine 监听 `cfg.Server.Port`，对外提供 JSON API。

### 模块分布
- `internal/handler`：HTTP 入口（道具、玩家、VIP、RCON、用户登陆等）。
- `internal/service`：业务逻辑、缓存读写、RCON 客户端、金币发放流程。
- `internal/dao`：基于 GORM 的数据访问层。
- `internal/middleware`：跨域（CORS）与 Token 鉴权白名单。
- `pkg/response` / `pkg/errcode`：统一响应体与状态码。
- `pkg/iputil`：IP2Region 加载与格式化。

## 目录速览
```
.
├── cmd/server/main.go        # 程序入口，负责配置加载、依赖注入
├── configs/                  # 多环境 YAML（dev/home/prod）
├── data/ip2region_*.xdb      # IPv4/IPv6 IP 库
├── internal/
│   ├── config/               # Viper 配置解析
│   ├── middleware/           # CORS + Auth
│   ├── router/               # /api/v1 路由注册
│   ├── handler/              # 各业务 HTTP Handler
│   ├── service/              # 业务逻辑、缓存、RCON
│   ├── dao/                  # GORM DAO
│   └── model/                # 数据结构
├── pkg/db                    # MySQL/Redis 初始化
├── pkg/iputil                # IP2Region 包装
├── pkg/response              # 响应结构
├── sql/                      # 初始化 SQL（道具、分类、金币等）
├── api.md                    # 详细 API 文档（中文）
└── README.md
```

## 技术栈
| 层级 | 技术 | 用途 |
| ---- | ---- | ---- |
| Web 框架 | [Gin 1.10](https://gin-gonic.com/) | 路由、请求处理 |
| ORM | [GORM 1.30](https://gorm.io/) + `gorm.io/driver/mysql` | 数据访问与迁移 |
| 缓存 | [go-redis v9](https://github.com/redis/go-redis) | Token & 业务缓存 |
| 配置 | [Viper 1.20](https://github.com/spf13/viper) | 多环境配置管理 |
| 日志 | [logrus 1.9](https://github.com/sirupsen/logrus) | 结构化日志 |
| RCON | 自研 `service.RconClient` | TCP 客户端、自动认证与分包 |
| IP 解析 | `github.com/lionsoul2014/ip2region` | 登录 IP 定位 |

## 快速开始
### 1. 环境要求
- Go 1.21+
- MySQL 5.7+（或兼容版本）
- Redis 5.0+
- 已启用 RCON 的 Ark 服务器（开放 Host/Port/Password）。
- IP2Region v4/v6 数据文件（已放入 `data/`，若自备请更新路径）。

### 2. 克隆并安装依赖
```bash
git clone https://github.com/your-org/icutool-ark-backend.git
cd icutool-ark-backend
go env -w GO111MODULE=on
go mod download
```

### 3. 准备配置
复制一份开发配置并根据实际修改数据库、Redis、RCON 等参数：
```bash
cp configs/config.dev.yaml configs/config.local.yaml  # 可选
# 或直接编辑 configs/config.dev.yaml
```
可用 `-env dev|home|prod` 切换，缺省值为 `home`。

### 4. 初始化数据库（任选其一）
1. **自动迁移**：首次启动会自动创建数据表。
2. **手动导入**：如需批量导入海量道具，可执行 `sql/ark_item.sql`、`sql/item_group.sql` 等脚本。

### 5. 启动服务
```bash
# 开发模式
go run ./cmd/server/main.go -env dev

# 生产部署建议
go build -o bin/ark-server ./cmd/server && ./bin/ark-server -env prod
```

### 6. 验证
```bash
# Health Check
curl http://localhost:8080/api/v1/ping

# 登录并获取 token
curl -X POST http://localhost:8080/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 携带 token 获取道具分页
curl -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/arkItem/queryByPage?kindType=1&pageNum=1&pageSize=20"
```

### 7. 运行测试
```bash
go test ./...
```

## 配置详解
所有配置位于 `configs/config.<env>.yaml`：
```yaml
server:
  port: 8080
mysql:
  dsn: "user:pass@tcp(127.0.0.1:3306)/ark?charset=utf8mb4&parseTime=True&loc=Local"
  max_open_conns: 100
  max_idle_conns: 10
redis:
  addr: "127.0.0.1:6379"
  password: ""
  db: 0
rcon:
  host: "game-server.local"
  port: 25575
  password: "your-rcon-password"
  require_auth: true
  timeout: 5000
  max_retries: 3
  retry_delay: 2000
ip2region:
  v4_xdb_path: "./data/ip2region_v4.xdb"
  v6_xdb_path: "./data/ip2region_v6.xdb"
```
- **server**：HTTP 监听端口。
- **mysql**：DSN 以及连接池配置。
- **redis**：缓存与 Token 存储库。
- **rcon**：Ark 服务器 RCON 信息；`require_auth` 控制是否发送认证包。
- **ip2region**：若路径不正确会导致登录定位功能降级但不影响主流程。

## 数据库与种子数据
- 首次运行会自动迁移核心模型。
- `sql/` 目录包含：
  - `ark_item.sql`：完整道具/恐龙 Blueprint 清单（体积约 600KB）。
  - `item_group.sql`、`kind_config.sql`：枚举配置。
  - `player_coins.sql`：示例金币表结构。
- 可以结合 `internal/dao` 了解字段定义；如需 schema 变更，建议通过 GORM migration 或 Goose/Flyway 统一管理。

## API 概览
详见 [`api.md`](api.md)。以下列出最常用的端点：
| 领域 | 路径 | 说明 |
| ---- | ---- | ---- |
| 健康检查 | `GET /api/v1/ping` | 返回 `pong`，可用于 K8s/SLB 探活 |
| 登录 | `POST /api/v1/user/login` | 返回 Token，Redis TTL 24h |
| Token 检查 | `GET /api/v1/user/check` | 校验 Token，有效则回写 `userId` |
| 道具分页 | `POST /api/v1/arkItem/queryByPage` | 按 `kindType`、`itemTypes`、关键字分页查询 |
| 道具详情 | `GET /api/v1/arkItem/:id` | 读取单个 Blueprint |
| 分组/类别 | `GET /api/v1/itemGroup/getAll`、`GET /api/v1/kindConfig/getAll` | 缓存 1h |
| RCON | `POST /api/v1/rcon/command`、`GET /api/v1/rcon/push`、`GET /api/v1/rcon/status` | 执行命令/发货/查询在线 |
| 玩家档案 | `GET /api/v1/arkPlayerAccount/queryByPage`、`POST /api/v1/arkPlayerAccount/updateAccount` | 管理玩家资产 |
| VIP | `GET /api/v1/arkVipConfig/getAll`、`POST /api/v1/arkVipConfig/update` | 维护 VIP 策略 |
| 金币日志 | `GET /api/v1/arkCoinRewardLog/queryByPage`、`POST /api/v1/arkCoinRewardLog/addCoins` | 追踪金币发放 |

## RCON 运维能力
`internal/service/rcon_client.go` 封装了：
- TCP 自动重连与鉴权失败回退；
- 处理 Ark RCON 多包响应（含超时控制与 ID 匹配）；
- 常用能力：
  - `SendArkCommand` → `giveitemtoplayer <uid> "<command>" <quantity> <quality> <blueprint>`。
  - `SendArkDinoCommand` → `spawnTamedDino <uid> <Blueprint> <level>`（自动补 `_C'` 后缀）。
  - `SayToAll` / `KickPlayer` / `BanPlayer` / `SaveWorld` / `GetAllPlayerInfo`。
- 对应 Handler 暴露以下 API：
  - `POST /rcon/command`：原生命令。
  - `POST /rcon/sendNotice`：`broadcast` 公告。
  - `GET /rcon/push`：发放物品。
  - `GET /rcon/pushDino`：发放恐龙。
  - `GET /rcon/status`、`/listAllPlayerInfo`、`/test`：状态查询。

使用建议：
1. 确认 Ark 服务器 `RCONEnabled=True` 且防火墙放行端口。
2. 若命令响应为空，请检查服务器语言/编码或 `require_auth` 配置。
3. 高并发发货可考虑在 Service 层增加排队与速率限制。

## 缓存策略
所有 Redis Key 统一前缀 `icutool:ark:`，主要 TTL 如下：
| Key | TTL | 用途 |
| --- | --- | --- |
| `login:token:{token}` | 24h | 用户登录态 |
| `item:list:{kindType}:{itemType}` | 30 min | 道具分页结果 |
| `item:id:{id}` | 1 h | 单个道具 |
| `itemGroup:list` / `itemGroup:id:{id}` | 1 h | 道具分组 |
| `kindConfig:list` / `kindConfig:id:{id}` | 1 h | 类型枚举 |
当 DAO 层发生 Insert/Update/Delete 时会主动清理对应缓存，保证读写一致性。

## 安全提示
- 当前示例登录账号/密码使用 MD5 存储，只适合作为占位。正式服建议：
  1. 改用 bcrypt/argon2，并增加多用户体系与 RBAC。
  2. 通过 HTTPS 或在网关层终止 TLS。
  3. 配置 `AuthMiddleware` 白名单仅保留必要接口。
- Token 仅保存在 Redis，不含刷新逻辑；如需长链保持可扩展 JWT/Refresh Token。
- `iputil` 仅用于标注登录地，不会中断主流程；如需合规可屏蔽该功能。

## Roadmap
- [ ] 接入真实 RBAC（角色/菜单/权限）。
- [ ] 提供 OpenAPI/Swagger 文档，方便前端/第三方调用。
- [ ] 导入导出道具/恐龙配置（CSV/Excel）。
- [ ] 发货/金币操作审计日志化。
- [ ] 增加 API 限流与操作告警。
- [ ] Docker 镜像与 CI/CD 流水线。

## 贡献指南
1. Fork 仓库并创建新分支（示例：`feature/rbac`）。
2. 保持 `go fmt`、`go test ./...` 通过；如有 linter 也请一并运行。
3. 附带必要的单元测试或手动验证步骤。
4. 提 PR 前请更新 `README`/`api.md` 中涉及的能力描述。
5. 在 PR 模板中说明测试环境、影响范围与回滚方案。

## English Quick Overview
- **What**: A Go (Gin + GORM) backend that automates Ark private-server operations—item search, RCON deliveries, player/VIP/coin management.
- **How**: Layered architecture with MySQL + Redis, token auth, IP geolocation, resilient RCON client and a full Chinese API guide (`api.md`).
- **Run**: `go run ./cmd/server/main.go -env dev`, configure MySQL/Redis/RCON via `configs/`, import SQL seeds if needed.
- **Docs**: Check `api.md` for every endpoint, `sql/` for schema/seed data, `data/` for ip2region databases.

## License
尚未在仓库中加入正式的开源许可证。发布前请新增 `LICENSE`（推荐 MIT / Apache-2.0）并在此处更新声明。