# 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-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ark Web Manage - 方舟游戏私服管理后台

[简体中文] | [English](#english)

## 快速开始

### 前置要求
- Go 1.21+
- MySQL 5.7+
- Redis 5.0+

### 项目初始化

1. **克隆项目** (略)

2. **配置文件**
   ```bash
   # 修改开发环境配置
   vim configs/config.dev.yaml
   
   # 修改生产环境配置
   vim configs/config.prod.yaml
   ```

3. **安装依赖**
   ```bash
   go mod download
   go mod tidy
   ```

4. **运行项目**
   ```bash
   # 开发环境
   go run ./cmd/server/main.go -env dev
   
   # 生产环境
   go run ./cmd/server/main.go -env prod
   ```

5. **测试API**
   ```bash
   # 登录
   curl -X POST http://localhost:8080/api/v1/user/login \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"123456"}'
   
   # 获取token后，查询物品
   curl -X GET "http://localhost:8080/api/v1/arkItem/queryByPage?kindType=1&pageNum=1&pageSize=20" \
     -H "Authorization: Bearer <your-token>"
   ```

---

## 项目概述

这是一个**方舟(ARK)游戏私服的管理后台API**，由Java版本迁移至Go语言实现。

### 核心功能
- 🎮 **物品管理** - 分页、搜索、详情查询
- 📦 **分组管理** - 分类和种类配置
- 🎯 **RCON控制** - 远程连接游戏服务器执行命令
- 👤 **用户认证** - Token-based身份验证

### 核心特性
- 使用Redis分布式缓存
- 支持RCON协议与游戏服务器通信
- 统一的API响应格式
- 完善的错误处理和日志记录

---

## API文档

详见 [api.md](api.md)

### 主要接口
```
POST   /api/v1/user/login           # 用户登录
GET    /api/v1/arkItem/queryByPage  # 分页查询物品
GET    /api/v1/arkItem/search       # 搜索物品
GET    /api/v1/rcon/push            # 推送物品给玩家
GET    /api/v1/rcon/status          # 获取服务器状态
```

---

## 项目结构

```
├── cmd/server/main.go              # 应用入口
├── configs/                         # 配置文件
├── internal/
│   ├── handler/                    # HTTP处理器
│   ├── service/                    # 业务逻辑
│   ├── dao/                        # 数据访问
│   ├── model/                      # 数据模型
│   ├── router/                     # 路由配置
│   └── middleware/                 # 中间件
├── pkg/
│   ├── db/                         # 数据库初始化
│   ├── errcode/                    # 错误码定义
│   └── response/                   # 响应工具
├── api.md                          # API文档
└── MIGRATION.md                    # 迁移总结
```

---

## 迁移总结

本项目由Java Spring Boot版本成功迁移至Go语言，详见 [MIGRATION.md](MIGRATION.md)

### 主要改进
✅ 从EhCache改为Redis分布式缓存  
✅ 改进的RCON协议实现  
✅ 清晰的代码结构和依赖注入  
✅ 性能优化和并发处理  

---

## 配置说明

### MySQL配置
```yaml
mysql:
  dsn: "user:password@tcp(127.0.0.1:3306)/database?charset=utf8mb4&parseTime=True&loc=Local"
  max_open_conns: 100
  max_idle_conns: 10
```

### Redis配置
```yaml
redis:
  addr: "127.0.0.1:6379"
  password: ""
  db: 0
```

### RCON配置
```yaml
rcon:
  host: "game-server.example.com"
  port: 25575
  password: "your-rcon-password"
  require_auth: true
  timeout: 5000
  max_retries: 3
  retry_delay: 2000
```

---

## 认证

### 登录流程
1. 调用 `POST /user/login` 获取token
2. 在后续请求中使用token进行认证
3. Token存储在Redis，有效期24小时

### 认证方式
```bash
# Header方式
Authorization: Bearer <token>

# 查询参数方式
?token=<token>
```

---

## Redis缓存

系统使用Redis作为分布式缓存，缓存键规范：

```
icutool:ark:item:list:{kindType}:{itemType}     # 物品列表 (30分钟)
icutool:ark:item:id:{id}                         # 物品详情 (1小时)
icutool:ark:itemgroup:list                       # 分组列表 (1小时)
icutool:ark:kindconfig:list                      # 种类列表 (1小时)
icutool:ark:login:token:{token}                  # 登录token (24小时)
```

---

## 常见问题

**Q: 如何修改端口？**  
A: 修改 `configs/config.dev.yaml` 中的 `server.port` 配置

**Q: 物品列表为空？**  
A: 需要先在MySQL的 `ark_item` 表中插入数据

**Q: RCON连接失败？**  
A: 检查游戏服务器是否开启RCON，以及配置的地址和密码是否正确

**Q: Token过期了？**  
A: 重新调用登录接口获取新token

---

## 后续开发

### 待实现功能
- [ ] 真实的用户认证逻辑
- [ ] 基于角色的访问控制 (RBAC)
- [ ] 物品导入/导出
- [ ] 审计日志记录
- [ ] API限流和降级

### 性能优化
- [ ] 数据库查询优化
- [ ] 缓存预热机制
- [ ] 连接池优化
- [ ] 分布式部署

---

## 技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Go | 1.21+ | 后端框架 |
| Gin | 最新 | Web框架 |
| GORM | 最新 | ORM框架 |
| MySQL | 5.7+ | 关系数据库 |
| Redis | 5.0+ | 缓存和Session |

---

## 开发者指南

### 添加新的API端点

1. **创建Handler**
   ```go
   // internal/handler/xxx_handler.go
   func (h *XxxHandler) YourMethod(c *gin.Context) {
       // 实现逻辑
   }
   ```

2. **创建Service**
   ```go
   // internal/service/xxx_service.go
   func (s *XxxService) YourMethod() {
       // 业务逻辑
   }
   ```

3. **创建DAO**
   ```go
   // internal/dao/xxx_dao.go
   func (d *XxxDAO) YourMethod() {
       // 数据访问
   }
   ```

4. **注册路由**
   ```go
   // internal/router/router.go
   v1.GET("/xxx/path", handler.YourMethod)
   ```

---

## 与原Java项目对比

| 方面 | Java版 | Go版 |
|------|--------|------|
| 缓存 | EhCache (本地) | Redis (分布式) |
| 连接管理 | 混乱 | 清晰 |
| 代码行数 | ~2000 | ~1500 |
| 编译大小 | ~100MB | ~20MB |
| 启动时间 | ~5秒 | <1秒 |
| 内存占用 | ~300MB | ~30MB |

---

## 许可证

[目前未指定许可证，请补充]

---

## 联系方式

如有问题或建议，请联系开发团队。

---

<a name="english"></a>

# English Version Coming Soon...

---

**最后更新**: 2024年  
**版本**: 1.0.0  
**状态**: Development Complete