添加 README 部署文档

2026-07-24 15:17:22 +08:00
parent 73047b74df
commit dde6f2c269
1 changed files with 179 additions and 0 deletions
@@ -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                   # 开发一键启动
+```