首次提交

deploy/deploy-readme.md

@@ -0,0 +1,252 @@
+# 寸进后端 — 宝塔面板部署指南
+
+> 部署包位置：`deploy/`（Linux amd64 二进制）
+
+---
+
+## 目录结构
+
+```
+deploy/
+├── inchstep-api    # Linux 可执行程序 (10.5 MB)
+├── .env            # 生产环境配置（请修改）
+├── start.sh        # 启动脚本（宝塔 Go 项目使用）
+└── 本文件          # 部署说明
+```
+
+---
+
+## 第一步：上传到服务器
+
+将 `deploy/` 目录整体上传到服务器，例如放到 `/www/wwwroot/inchstep/`：
+
+```bash
+# 解压（如果是 zip 压缩包）
+unzip inchstep-deploy.zip -d /www/wwwroot/inchstep
+
+# 给二进制加执行权限
+chmod +x /www/wwwroot/inchstep/inchstep-api
+chmod +x /www/wwwroot/inchstep/start.sh
+```
+
+---
+
+## 第二步：配置环境变量
+
+编辑 `.env` 文件，修改以下关键配置：
+
+```ini
+# 数据库密码（必改）
+DB_PASS=你的MySQL密码
+
+# JWT 密钥（必改，建议生成 64 位随机字符）
+JWT_SECRET=your-strong-random-secret-string
+
+# Redis 地址（如果 Redis 不在本机）
+REDIS_URL=redis://你的Redis地址:6379/0
+```
+
+> 生产环境 **必须** 修改 `DB_PASS` 和 `JWT_SECRET`，否则存在安全风险。
+
+---
+
+## 第三步：宝塔面板配置
+
+### 3.1 安装 Go 项目插件
+
+宝塔面板 → 软件商店 → 搜索 "Go项目" → 安装
+
+### 3.2 添加 Go 项目
+
+宝塔面板 → Go项目 → 添加Go项目：
+
+| 配置项 | 值 |
+|--------|-----|
+| 项目名称 | `inchstep` |
+| 项目路径 | `/www/wwwroot/inchstep` |
+| 可执行文件 | `/www/wwwroot/inchstep/inchstep-api` |
+| 项目端口 | `8080` |
+| 运行用户 | `www` |
+| 开机启动 | ✅ 勾选 |
+
+### 3.3 方法 A：使用 .env 文件
+
+二进制会自动读取同目录下的 `.env` 文件。上传后无需额外操作。
+
+### 3.4 方法 B：在宝塔面板设置环境变量（可选）
+
+如果不想用 `.env` 文件，可以在宝塔 Go 项目配置的"环境变量"中逐条添加：
+
+```
+PORT=8080
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_USER=root
+DB_PASS=你的MySQL密码
+DB_NAME=inchstep
+JWT_SECRET=你的JWT密钥
+REDIS_URL=redis://127.0.0.1:6379/0
+```
+
+> 方法 B 优先级高于 `.env` 文件。两种方式二选一即可。
+
+---
+
+## 第四步：准备数据库
+
+宝塔面板 → 数据库 → 添加数据库：
+
+| 配置项 | 值 |
+|--------|-----|
+| 数据库名 | `inchstep` |
+| 用户名 | `inchstep`（或 root） |
+| 密码 | 与 `.env` 中的 `DB_PASS` 一致 |
+| 字符集 | `utf8mb4` |
+
+> 数据库 **无需手动建表**。首次启动时会自动通过 GORM AutoMigrate 创建全部表结构，并初始化 10 个成就徽章和超级管理员账号。
+
+---
+
+## 第五步：启动
+
+在宝塔 Go 项目页面点击"启动"。
+
+首次日志示例：
+
+```
+启动成功
+表结构自动创建完成
+成就数据初始化完成
+默认管理员账号: admin / admin123456
+寸进 API 服务启动于 :8080
+```
+
+### 验证是否启动成功
+
+```bash
+curl http://localhost:8080/health
+# → {"status":"ok"}
+```
+
+---
+
+## 第六步：设置反向代理（可选）
+
+如果需要通过域名访问（例如 `https://api.inchstep.com`）：
+
+宝塔面板 → 网站 → 添加站点 → 设置 → 反向代理：
+
+| 配置项 | 值 |
+|--------|-----|
+| 目标 URL | `http://localhost:8080` |
+| 发送域名 | `api.inchstep.com`（你的域名） |
+
+---
+
+## 常见问题
+
+### Q: 启动后提示端口被占用
+
+```bash
+# 查看端口占用
+lsof -i:8080
+# 或修改 .env 中的 PORT 为其他端口（如 8081）
+```
+
+### Q: 连接数据库失败
+
+1. 检查 `.env` 中的 DB_HOST 是否为 `127.0.0.1`
+2. 确认 MySQL 已启动：`systemctl status mysqld`
+3. 确认数据库 `inchstep` 已创建
+
+### Q: 启动后访问 /health 无响应
+
+```bash
+# 检查项目是否在运行
+ps aux | grep inchstep-api
+
+# 查看启动日志
+cat /www/wwwroot/inchstep/logs/*.log 2>/dev/null
+
+# 或在宝塔 Go 项目页面查看运行状态
+```
+
+### Q: 如何更新版本？
+
+```bash
+# 1. 在宝塔停止项目
+# 2. 上传新二进制覆盖
+chmod +x /www/wwwroot/inchstep/inchstep-api
+# 3. 在宝塔启动项目
+```
+
+---
+
+## 默认管理员账号
+
+首次启动会自动创建：
+
+| 用户名 | 密码 | 角色 |
+|--------|------|------|
+| `admin` | `admin123456` | 超级管理员 |
+
+> **生产环境请及时修改默认密码**：登录管理后台后 → 管理员管理 → 新增其他管理员后禁用默认账号。
+
+---
+
+## 数据库连接失败？请按以下步骤排查
+
+### 1. 确认 MySQL 密码
+
+`ash
+# 用你的密码直接连接 MySQL
+mysql -uroot -p你的密码 -e "SELECT 1;"
+`
+
+如果上面的命令返回 1，说明密码正确。否则密码不对。
+
+### 2. 宝塔中查看/重置密码
+
+宝塔面板 → 数据库 → root 密码 → 查看或重置
+
+> 重置密码后请同步更新 .env 中的 DB_PASS
+
+### 3. 确认数据库已创建
+
+`ash
+mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS inchstep CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+`
+
+### 4. 确认 MySQL 端口
+
+`ash
+mysql -uroot -p -e "SHOW VARIABLES LIKE 'port';"
+# 宝塔默认是 3306
+`
+
+### 5. 确认 MySQL 正在运行
+
+`ash
+systemctl status mysqld
+# 或
+/etc/init.d/mysqld status
+`
+
+### 6. 常见错误对照
+
+| 错误信息 | 原因 | 解决 |
+|---------|------|------|
+| Access denied for user 'root'@'localhost' | 密码错误 | 检查 .env 中的 DB_PASS |
+| Can't connect to MySQL server | MySQL 未运行或地址/端口不对 | systemctl start mysqld，检查 DB_HOST/DB_PORT |
+| Unknown database 'inchstep' | 数据库未创建 | 执行 CREATE DATABASE inchstep ... |
+| connection refused | 端口不对或 MySQL 未监听 | 检查 DB_PORT 和 
+etstat -tlnp \| grep 3306 |
+
+### 7. .env 文件路径说明
+
+程序会按以下顺序查找 .env：
+
+1. 当前工作目录（宝塔运行 Go 项目时的工作目录）
+2. 可执行文件所在的目录
+
+确保 .env 与 inchstep-api 放在**同一个目录**下。