inchstep/deploy/deploy-readme.md

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

部署包位置：deploy/（Linux amd64 二进制）

---

目录结构

deploy/
├── inchstep-api    # Linux 可执行程序 (10.5 MB)
├── .env            # 生产环境配置（请修改）
├── start.sh        # 启动脚本（宝塔 Go 项目使用）
└── 本文件          # 部署说明

---

第一步：上传到服务器

将 deploy/ 目录整体上传到服务器，例如放到 /www/wwwroot/inchstep/：

# 解压（如果是 zip 压缩包）
unzip inchstep-deploy.zip -d /www/wwwroot/inchstep

# 给二进制加执行权限
chmod +x /www/wwwroot/inchstep/inchstep-api
chmod +x /www/wwwroot/inchstep/start.sh

---

第二步：配置环境变量

编辑 .env 文件，修改以下关键配置：

# 数据库密码（必改）
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

验证是否启动成功

curl http://localhost:8080/health
# → {"status":"ok"}

---

第六步：设置反向代理（可选）

如果需要通过域名访问（例如 https://api.inchstep.com）：

宝塔面板 → 网站 → 添加站点 → 设置 → 反向代理：

配置项	值
目标 URL	http://localhost:8080
发送域名	api.inchstep.com（你的域名）

---

常见问题

Q: 启动后提示端口被占用

# 查看端口占用
lsof -i:8080
# 或修改 .env 中的 PORT 为其他端口（如 8081）

Q: 连接数据库失败

1. 检查 .env 中的 DB_HOST 是否为 127.0.0.1
2. 确认 MySQL 已启动：systemctl status mysqld
3. 确认数据库 inchstep 已创建

Q: 启动后访问 /health 无响应

# 检查项目是否在运行
ps aux | grep inchstep-api

# 查看启动日志
cat /www/wwwroot/inchstep/logs/*.log 2>/dev/null

# 或在宝塔 Go 项目页面查看运行状态

Q: 如何更新版本？

# 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 放在同一个目录下。