docs: 部署方法固化进仓库（一键部署脚本 + 完整运维文档）
之前部署用的 SSH 助手放在系统临时目录里，重启就丢了，下一位接手时根本拿不到。 现在把它搬进仓库并补齐文档： 新增 - scripts/ssh-helper.js：SSH 执行与 SFTP 上传。Windows 自带 OpenSSH 但没有 sshpass/plink，无法非交互传密码，所以用 ssh2 直接实现协议层。 凭据全部走环境变量（SSH_HOST/SSH_PORT/SSH_USER/SSH_PASS），脚本里不含任何密钥； ssh2 是 devDependencies，未安装时提示安装而不是裸崩 - scripts/deploy.js：一键部署 —— 打包 → 上传 → 远程执行 update.sh → 轮询确认控制台返回 200，任一步失败都明确报错。可选 DEPLOY_APP / DEPLOY_PORT - npm scripts：deploy、ssh 文档 - TODO.md 新增「部署方法」章节：一键部署与手动部署两种步骤、辅助脚本说明、 update.sh 的行为、pm2 与日志的常用运维命令（含回滚）、服务器上关键文件清单、 新增环境变量时的三件事（.env 真实值 + .env.example 占位符 + 确认 gitignore） - README「部署到服务器」开头加一键更新说明，并指向 TODO.md 的完整章节 - 顺带提醒旧版 Fabric 模组源码在临时目录里会被清理，接手后建议先备份 测试 368 全绿；一键部署已实跑验证（4/4 校验通过，控制台 200 OK）。
这个提交包含在：
lyizai
@@ -12,12 +12,12 @@
|
||||
| 项 | 值 |
|
||||
| --- | --- |
|
||||
| 技术栈 | Node.js ≥ 22 + mineflayer 4.39.0 + mineflayer-pathfinder 2.4.5 |
|
||||
| 测试 | `npm test`（363 个用例全绿） |
|
||||
| 测试 | `npm test`（368 个用例全绿） |
|
||||
| 语法与前端 id 自检 | `npm run check` |
|
||||
| 本地启动 | `npm start`（控制台 http://127.0.0.1:3080/） |
|
||||
| 服务器 | `root@103.236.99.177:33851`，部署目录 `/opt/autostore-bot` |
|
||||
| 控制台 | http://103.236.99.177:78/ ，密码在服务器 `.env` 的 `WEB_PASSWORD` |
|
||||
| 进程管理 | pm2 应用 `autostore-bot`（端口 78）；旧版 Fabric 机器人为 `minecraft-bot`（端口 91，已停） |
|
||||
| 更新方式 | 打包上传 → `bash /opt/autostore-bot/update.sh`（保留 `.env` / `data/` / `node_modules/` / `runtime/`） |
|
||||
| 私有 Node | `/opt/autostore-bot/runtime/current/bin/node`（v24.16.0） |
|
||||
|
||||
**旧版 Fabric 模组源码**（重要参考，实机可用的实现）：
|
||||
@@ -25,6 +25,111 @@
|
||||
它在这台服务器上是**真的能走路、能寻路、能扩地**的，所以遇到 mineflayer 行为诡异时，
|
||||
第一件事应该是拿它的实现逐项对照，而不是自己猜。
|
||||
|
||||
> ⚠️ 上面的临时目录会被系统清理。若已丢失，它只作为历史参考 ——
|
||||
> 不影响当前项目运行，但排查移动问题时很有价值，建议接手后先备份一份到仓库外。
|
||||
|
||||
---
|
||||
|
||||
## 0.1 🚀 部署方法（完整步骤）
|
||||
|
||||
### 方式一：一键部署（推荐）
|
||||
|
||||
```powershell
|
||||
# Windows PowerShell
|
||||
$env:SSH_HOST='103.236.99.177'; $env:SSH_PORT='33851'
|
||||
$env:SSH_USER='root'; $env:SSH_PASS='<服务器密码>'
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
SSH_HOST=103.236.99.177 SSH_PORT=33851 SSH_USER=root SSH_PASS='<密码>' npm run deploy
|
||||
```
|
||||
|
||||
`scripts/deploy.js` 会依次做：打包 → 上传 → 远程执行 `update.sh` →
|
||||
轮询确认控制台返回 200。任一步失败都会明确报错。
|
||||
|
||||
可选环境变量：`DEPLOY_APP`（默认 `/opt/autostore-bot`）、`DEPLOY_PORT`（默认 `78`）。
|
||||
|
||||
### 方式二：手动部署
|
||||
|
||||
```bash
|
||||
# 1. 打包（务必排除 data / .env / node_modules，否则会覆盖服务器上的真实数据）
|
||||
tar -czf update.tar.gz \
|
||||
--exclude=node_modules --exclude=.git --exclude=data --exclude='*.log' --exclude=.env \
|
||||
-C . .
|
||||
|
||||
# 2. 上传
|
||||
scp -P 33851 update.tar.gz root@103.236.99.177:/opt/autostore-bot/update.tar.gz
|
||||
|
||||
# 3. 远程应用（update.sh 会保留 .env / data / node_modules / runtime）
|
||||
ssh -p 33851 root@103.236.99.177 'bash /opt/autostore-bot/update.sh'
|
||||
```
|
||||
|
||||
### 辅助脚本
|
||||
|
||||
| 脚本 | 用途 |
|
||||
| --- | --- |
|
||||
| `scripts/deploy.js` | 一键部署（推荐） |
|
||||
| `scripts/ssh-helper.js` | 单条远程命令 / 上传：`node scripts/ssh-helper.js exec "<命令>"`、`... put <本地> <远程>` |
|
||||
|
||||
Windows 自带 OpenSSH 但**没有 sshpass / plink**，无法非交互传密码，
|
||||
所以这两个脚本用 `ssh2` 直接实现协议层（`ssh2` 是 devDependencies，
|
||||
未安装时脚本会提示 `npm install --save-dev ssh2` 而不是裸崩）。
|
||||
|
||||
**凭据一律走环境变量，脚本里不写死任何密码。**
|
||||
|
||||
### update.sh 做了什么
|
||||
|
||||
`/opt/autostore-bot/update.sh` 的行为：
|
||||
1. 解压 `update.tar.gz` 到 `/opt/autostore-bot`（**保留** `.env`、`data/`、`node_modules/`、`runtime/`）
|
||||
2. 用私有 Node 重新安装/校验依赖
|
||||
3. `pm2 restart autostore-bot --update-env`
|
||||
4. 打印进程状态与端口监听情况
|
||||
|
||||
### 常用运维命令
|
||||
|
||||
```bash
|
||||
# 进程状态
|
||||
pm2 status
|
||||
pm2 list
|
||||
|
||||
# 重启 / 停止
|
||||
pm2 restart autostore-bot --update-env
|
||||
pm2 stop autostore-bot
|
||||
|
||||
# 日志（实时）
|
||||
tail -f /opt/autostore-bot/data/pm2-out.log # 运行日志
|
||||
tail -f /opt/autostore-bot/data/pm2-error.log # 告警与错误
|
||||
pm2 logs autostore-bot
|
||||
|
||||
# 端口
|
||||
ss -lntp | grep ':78 '
|
||||
|
||||
# 回滚：把上一份备份目录改回来（update.sh 会先备份旧版本目录）
|
||||
ls -1d /opt/autostore-bot/backup-* 2>/dev/null | tail -3
|
||||
```
|
||||
|
||||
### 服务器上的关键文件
|
||||
|
||||
| 路径 | 说明 |
|
||||
| --- | --- |
|
||||
| `/opt/autostore-bot/.env` | **真实凭据**（`MC_USERNAME`、`MC_PASSWORD`、`WEB_PASSWORD`、`SIMP_API_KEY`、`SIMP_API_V2_KEY`），权限 0600，**绝不进仓库** |
|
||||
| `/opt/autostore-bot/data/autostore.json` | 运行时配置（控制台保存的），会被 `update.sh` 保留 |
|
||||
| `/opt/autostore-bot/data/bots.json` | 机器人非敏感设置 |
|
||||
| `/opt/autostore-bot/data/bots.credentials.json` | 界面添加的账号密码，权限 0600 |
|
||||
| `/opt/autostore-bot/data/chat/<玩家名>.jsonl` | 公屏完整日志 |
|
||||
| `/opt/autostore-bot/data/expansion-log.jsonl` | 开拓日志 |
|
||||
| `/opt/autostore-bot/data/mapcache/` | 大地图瓦片缓存 |
|
||||
| `/opt/autostore-bot/ecosystem.config.js` | pm2 配置 |
|
||||
| `/opt/autostore-bot/runtime/current` | 私有 Node（服务器自带 Node 太旧时用） |
|
||||
|
||||
### 新增环境变量时
|
||||
|
||||
1. 在 `.env` 里加真实值（**只在服务器上加，不要提交**）；
|
||||
2. 在 `.env.example` 里加**占位符**（如 `<your-xxx-key>`），绝不含真实密钥；
|
||||
3. 确认 `.gitignore` 已包含 `.env`（本项目已含，并有 `!.env.example` 例外）。
|
||||
|
||||
---
|
||||
|
||||
## 1. 🔴 最大问题：寻路器驱动的移动会被服务端持续回弹
|
||||
|
||||
在新工单中引用
屏蔽一个用户