inchstep/deploy/deploy-readme.md

# 寸进后端 — 宝塔面板部署指南

> 部署包位置：`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 放在**同一个目录**下。