添加 README 部署文档
This commit is contained in:
yml2213
@@ -0,0 +1,179 @@
|
|||||||
|
# 游戏皮肤分销管理系统
|
||||||
|
|
||||||
|
基于 Go + React 的游戏皮肤分销管理平台，支持分销商管理、订单追踪、上游皮肤源头对接。
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
| 层级 | 技术 |
|
||||||
|
|------|------|
|
||||||
|
| 后端 | Go 1.26 + Gin + GORM |
|
||||||
|
| 数据库 | PostgreSQL 16 |
|
||||||
|
| 前端 | React 19 + TypeScript + Ant Design |
|
||||||
|
| 构建 | Vite + Docker Compose |
|
||||||
|
| 反向代理 | Caddy |
|
||||||
|
|
||||||
|
## 本地开发
|
||||||
|
|
||||||
|
### 环境要求
|
||||||
|
|
||||||
|
- Go 1.26+
|
||||||
|
- Node.js 22+
|
||||||
|
- Docker（用于自动启动 PostgreSQL 开发容器）
|
||||||
|
|
||||||
|
### 快速启动
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 复制配置文件
|
||||||
|
cp .env.example .env
|
||||||
|
# 按需修改 .env 中的密钥
|
||||||
|
|
||||||
|
# 2. 一键启动（后端 + 前端 + PostgreSQL）
|
||||||
|
make dev
|
||||||
|
# 或直接
|
||||||
|
./start.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
启动后：
|
||||||
|
- 前端：`http://localhost:5173`
|
||||||
|
- 后端：`http://localhost:8080`
|
||||||
|
- 默认管理员：`admin` / `admin123`
|
||||||
|
|
||||||
|
按 `Ctrl+C` 停止所有服务。
|
||||||
|
|
||||||
|
### 手动启动
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装依赖
|
||||||
|
make install
|
||||||
|
|
||||||
|
# 分别启动
|
||||||
|
make backend # 后端 :8080
|
||||||
|
make frontend # 前端 :5173
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker 生产部署
|
||||||
|
|
||||||
|
### 配置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
# 编辑 .env，确保以下变量已配置：
|
||||||
|
# JWT_SECRET — 生产环境务必修改
|
||||||
|
# OPEN_API_KEY — 皮肤源头对接 API Key
|
||||||
|
# OPEN_API_SECRET — 签名密钥
|
||||||
|
# DATABASE_URL — PostgreSQL 连接，容器内主机名为 postgres
|
||||||
|
```
|
||||||
|
|
||||||
|
> 国内服务器可在 `.env` 中取消 `GOPROXY`、`ALPINE_MIRROR`、`NPM_REGISTRY` 等镜像加速源的注释。
|
||||||
|
|
||||||
|
### 启动服务
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 构建并启动全部服务（PostgreSQL + 后端 + Caddy）
|
||||||
|
make docker-up
|
||||||
|
# 或
|
||||||
|
docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
服务端口：
|
||||||
|
- `:80` — 前端页面 + API（Caddy 统一入口）
|
||||||
|
- `:8080` — 后端 API（直接访问，调试用）
|
||||||
|
|
||||||
|
### 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make docker-logs # 查看日志
|
||||||
|
make docker-ps # 查看容器状态
|
||||||
|
make docker-down # 停止并移除
|
||||||
|
```
|
||||||
|
|
||||||
|
### 自定义域名
|
||||||
|
|
||||||
|
修改 `Caddyfile` 中的域名 `skin.khhao.com` 为你的域名，重新构建即可。
|
||||||
|
|
||||||
|
## 环境变量
|
||||||
|
|
||||||
|
| 变量 | 说明 | 默认值 |
|
||||||
|
|------|------|--------|
|
||||||
|
| `PORT` | 后端端口 | `8080` |
|
||||||
|
| `JWT_SECRET` | JWT 签名密钥 | 开发默认值 |
|
||||||
|
| `DATABASE_URL` | PostgreSQL 连接串 | 本地开发默认值 |
|
||||||
|
| `GIN_MODE` | Gin 运行模式 | `debug` |
|
||||||
|
| `OPEN_API_KEY` | 开放接口 ApiKey | 需修改 |
|
||||||
|
| `OPEN_API_SECRET` | 开放接口签名密钥 | 需修改 |
|
||||||
|
| `OPEN_SIGN_SKEW` | 签名时间戳偏差（秒） | `300` |
|
||||||
|
| `OPEN_API_DEBUG` | 开放接口调试日志 | debug 模式默认开启 |
|
||||||
|
| `LOG_FILE` | 日志文件路径 | `logs/app.log` |
|
||||||
|
|
||||||
|
## 开放接口（皮肤源头对接）
|
||||||
|
|
||||||
|
上游皮肤源头系统通过以下接口对接，需携带签名头 `X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Sign`。
|
||||||
|
|
||||||
|
### 1. 查询订单（发货前置）
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/open/v1/orders/:order_no
|
||||||
|
```
|
||||||
|
|
||||||
|
返回订单状态、商品信息、是否可发货。
|
||||||
|
|
||||||
|
### 2. 发货结果通知
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/open/v1/orders/ship-notify
|
||||||
|
```
|
||||||
|
|
||||||
|
上游发货完成后推送结果，请求体：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"order_no": "O202607241200000012",
|
||||||
|
"ship_status": "success",
|
||||||
|
"provider_order_no": "上游单号",
|
||||||
|
"shipped_at": "2026-07-24T16:00:00+08:00",
|
||||||
|
"fail_reason": "",
|
||||||
|
"game_channel": "IOS-微信",
|
||||||
|
"game_uid": "550e8400-e29b-41d4-a716-446655440000",
|
||||||
|
"role_name": "玩家名",
|
||||||
|
"pay_score": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 字段 | 必填 | 说明 |
|
||||||
|
|------|------|------|
|
||||||
|
| `order_no` | 是 | 系统订单号 |
|
||||||
|
| `ship_status` | 是 | `success` / `failed` / `processing` |
|
||||||
|
| `provider_order_no` | 否 | 上游单号 |
|
||||||
|
| `shipped_at` | 否 | 发货时间，RFC3339 格式 |
|
||||||
|
| `fail_reason` | 否 | 失败原因 |
|
||||||
|
| `game_channel` | 否 | 账号区服（安卓/IOS-微信/QQ） |
|
||||||
|
| `game_uid` | 否 | 游戏角色 UUID |
|
||||||
|
| `role_name` | 否 | 角色名 |
|
||||||
|
| `pay_score` | 否 | 消耗积分 |
|
||||||
|
|
||||||
|
## 管理端
|
||||||
|
|
||||||
|
管理员登录后可访问商品管理、订单管理、用户管理、发货日志等功能。后台默认地址 `/`。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
```
|
||||||
|
├── backend/
|
||||||
|
│ ├── cmd/server/main.go # 入口
|
||||||
|
│ └── internal/
|
||||||
|
│ ├── config/ # 配置加载
|
||||||
|
│ ├── handler/ # HTTP 处理器
|
||||||
|
│ ├── middleware/ # JWT 认证、签名验证
|
||||||
|
│ ├── model/ # 数据模型
|
||||||
|
│ ├── pkg/ # 工具包
|
||||||
|
│ ├── router/ # 路由
|
||||||
|
│ └── service/ # 业务逻辑
|
||||||
|
├── frontend/src/
|
||||||
|
│ ├── api/ # API 调用
|
||||||
|
│ ├── pages/ # 页面组件
|
||||||
|
│ ├── layouts/ # 布局
|
||||||
|
│ └── types/ # 类型定义
|
||||||
|
├── docker-compose.yml # 容器编排
|
||||||
|
├── Makefile # 常用命令
|
||||||
|
└── start.sh # 开发一键启动
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user