542 lines
11 KiB
Markdown
542 lines
11 KiB
Markdown
# 3588AdminBackend 部署脚本使用说明
|
||
|
||
> 本目录包含 3588AdminBackend 的统一管理脚本，支持离线环境下的安装、升级、卸载和日常运维。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [快速开始](#快速开始)
|
||
2. [脚本清单](#脚本清单)
|
||
3. [详细使用指南](#详细使用指南)
|
||
4. [典型使用场景](#典型使用场景)
|
||
5. [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 第一次部署（离线环境）
|
||
|
||
```bash
|
||
# 1. 挂载光盘/USB 后进入目录
|
||
cd /mnt/cdrom/3588admin-deploy
|
||
|
||
# 2. 检查环境
|
||
sudo ./scripts/3588admin check
|
||
|
||
# 3. 执行安装
|
||
sudo ./scripts/3588admin install
|
||
|
||
# 4. 修改配置
|
||
sudo nano /opt/3588admin/config/managerd.json
|
||
|
||
# 5. 启动服务
|
||
sudo 3588admin start
|
||
|
||
# 6. 查看状态
|
||
sudo 3588admin status
|
||
```
|
||
|
||
---
|
||
|
||
## 脚本清单
|
||
|
||
| 脚本 | 用途 | 执行位置 |
|
||
|------|------|----------|
|
||
| `3588admin` | **统一管理脚本**（安装/状态/升级/卸载/启动/停止） | 目标机器 |
|
||
| `build-offline-package.sh` | 构建离线部署包 | 联网机器 |
|
||
| `3588admin.service` | Systemd 服务文件 | 安装时复制 |
|
||
|
||
---
|
||
|
||
## 详细使用指南
|
||
|
||
### 3588admin 管理脚本
|
||
|
||
**3588admin** 是统一的管理脚本，整合了过去分散的多个脚本功能。
|
||
|
||
#### 命令概览
|
||
|
||
```bash
|
||
3588admin <命令> [选项]
|
||
```
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `install [目录]` | 安装服务 | `sudo 3588admin install` |
|
||
| `status` | 查看服务状态 | `sudo 3588admin status` |
|
||
| `start` | 启动服务 | `sudo 3588admin start` |
|
||
| `stop` | 停止服务 | `sudo 3588admin stop` |
|
||
| `restart` | 重启服务 | `sudo 3588admin restart` |
|
||
| `upgrade [目录]` | 升级服务（保留配置） | `sudo 3588admin upgrade` |
|
||
| `uninstall [目录]` | 卸载服务（自动备份配置） | `sudo 3588admin uninstall` |
|
||
| `check` | 检查环境是否满足要求 | `sudo 3588admin check` |
|
||
| `help` | 显示帮助信息 | `3588admin help` |
|
||
|
||
#### install - 安装服务
|
||
|
||
**语法**:
|
||
```bash
|
||
sudo 3588admin install [安装目录]
|
||
```
|
||
|
||
**参数**:
|
||
- `安装目录`: 可选，默认为 `/opt/3588admin`
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 默认安装到 /opt/3588admin
|
||
sudo ./scripts/3588admin install
|
||
|
||
# 自定义安装目录
|
||
sudo ./scripts/3588admin install /usr/local/3588admin
|
||
```
|
||
|
||
**安装流程**:
|
||
1. 检查 root 权限
|
||
2. 安装依赖包（如有）
|
||
3. 创建安装目录
|
||
4. 复制二进制文件、配置、脚本
|
||
5. 设置执行权限
|
||
6. 创建命令快捷方式（`3588admin-start` 等）
|
||
7. 安装 Systemd 服务（可选）
|
||
|
||
**安装后操作**:
|
||
```bash
|
||
# 编辑配置文件
|
||
sudo nano /opt/3588admin/config/managerd.json
|
||
|
||
# 特别注意修改:
|
||
# - agent_token: 改为安全的随机字符串
|
||
# - listen: 如需外部访问改为 "0.0.0.0:18080"
|
||
```
|
||
|
||
---
|
||
|
||
#### status - 查看状态
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 方式1: 使用快捷命令（推荐）
|
||
sudo 3588admin-status
|
||
|
||
# 方式2: 直接执行
|
||
sudo 3588admin status
|
||
```
|
||
|
||
**显示内容**:
|
||
- 基本信息（目录、配置文件路径）
|
||
- 二进制文件状态
|
||
- 配置文件内容和监听地址
|
||
- 进程状态（运行/停止）
|
||
- CPU/内存使用情况
|
||
- 网络端口监听状态
|
||
- HTTP API 连通性测试
|
||
- 最新日志
|
||
|
||
---
|
||
|
||
#### start - 启动服务
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 方式1: 使用快捷命令（推荐）
|
||
sudo 3588admin-start
|
||
|
||
# 方式2: 直接执行
|
||
sudo 3588admin start
|
||
```
|
||
|
||
**功能**:
|
||
- 检查配置文件是否存在且格式正确
|
||
- 检查服务是否已在运行
|
||
- 后台启动服务并记录 PID
|
||
- 显示启动结果
|
||
|
||
---
|
||
|
||
#### stop - 停止服务
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 方式1: 使用快捷命令（推荐）
|
||
sudo 3588admin-stop
|
||
|
||
# 方式2: 直接执行
|
||
sudo 3588admin stop
|
||
```
|
||
|
||
**功能**:
|
||
- 优雅停止（发送 SIGTERM，等待最多 10 秒）
|
||
- 强制结束（如优雅停止失败）
|
||
- 清理 PID 文件
|
||
|
||
---
|
||
|
||
#### restart - 重启服务
|
||
|
||
**使用方法**:
|
||
```bash
|
||
sudo 3588admin restart
|
||
```
|
||
|
||
---
|
||
|
||
#### upgrade - 升级服务
|
||
|
||
**用途**: 升级到新版本（保留配置）
|
||
|
||
**语法**:
|
||
```bash
|
||
sudo 3588admin upgrade [安装目录]
|
||
```
|
||
|
||
**参数**:
|
||
- `安装目录`: 可选，默认为 `/opt/3588admin`
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 升级流程
|
||
# 1. 停止服务
|
||
# 2. 备份现有数据和配置
|
||
# 3. 更新二进制文件
|
||
# 4. 更新脚本
|
||
# 5. 启动服务
|
||
|
||
sudo ./scripts/3588admin upgrade
|
||
```
|
||
|
||
**升级前准备**:
|
||
1. 在新的部署包中确认 `bin/managerd` 是新版本
|
||
2. 执行升级命令
|
||
|
||
**回滚方法**:
|
||
```bash
|
||
# 如升级后有问题，快速回滚
|
||
sudo 3588admin stop
|
||
sudo cp /root/3588admin-backup-xxx/managerd.old /opt/3588admin/bin/managerd
|
||
sudo 3588admin start
|
||
```
|
||
|
||
---
|
||
|
||
#### uninstall - 卸载服务
|
||
|
||
**用途**: 完全卸载 3588AdminBackend
|
||
|
||
**语法**:
|
||
```bash
|
||
sudo 3588admin uninstall [安装目录]
|
||
```
|
||
|
||
**参数**:
|
||
- `安装目录`: 可选，默认为 `/opt/3588admin`
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 默认卸载
|
||
sudo ./scripts/3588admin uninstall
|
||
|
||
# 卸载自定义目录
|
||
sudo ./scripts/3588admin uninstall /usr/local/3588admin
|
||
```
|
||
|
||
**卸载内容**:
|
||
- 停止服务
|
||
- 删除 Systemd 服务
|
||
- 删除命令快捷方式
|
||
- 删除安装目录（会自动备份配置）
|
||
|
||
**注意**: 卸载前会自动备份 `managerd.json` 到 `/root/3588admin-backup-YYYYMMDDhhmmss/`
|
||
|
||
---
|
||
|
||
#### check - 环境检查
|
||
|
||
**用途**: 检查目标系统是否满足运行要求
|
||
|
||
**执行环境**: 目标 Ubuntu 22.04 服务器
|
||
|
||
**检查项**:
|
||
- 操作系统版本
|
||
- CPU 架构
|
||
- 端口占用情况（18080/TCP, 35688/UDP）
|
||
- 防火墙配置
|
||
- 磁盘空间
|
||
- 必要工具
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 安装前检查
|
||
sudo ./scripts/3588admin check
|
||
```
|
||
|
||
**输出示例**:
|
||
```
|
||
========== 3588AdminBackend 环境检查 ==========
|
||
|
||
[系统信息]
|
||
主机名: server01
|
||
操作系统: Ubuntu 22.04.5 LTS
|
||
✓ Ubuntu 22.04 detected
|
||
|
||
[硬件信息]
|
||
架构: x86_64
|
||
✓ x86_64 架构
|
||
CPU: 4 核
|
||
内存: 7.7Gi
|
||
|
||
[端口检查]
|
||
✓ 端口 18080 可用
|
||
✓ 端口 35688 可用
|
||
|
||
...
|
||
|
||
========== 检查总结 ==========
|
||
通过: 12 警告: 0 失败: 0
|
||
✓ 环境检查全部通过，可以安装
|
||
```
|
||
|
||
---
|
||
|
||
### build-offline-package.sh
|
||
|
||
**用途**: 在联网机器上构建完整的离线部署包
|
||
|
||
**执行环境**: 有网络的 Linux 机器（Ubuntu/Debian/CentOS）
|
||
|
||
**前置条件**:
|
||
- Go 1.23+ 已安装
|
||
- 项目源码完整
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 在项目目录下执行
|
||
cd scripts/deploy
|
||
./build-offline-package.sh
|
||
|
||
# 输出位置: build/3588AdminBackend-离线部署包-YYYYMMDD.tar.gz
|
||
```
|
||
|
||
**输出内容**:
|
||
```
|
||
build/3588AdminBackend-离线部署包-20260225/
|
||
├── bin/managerd # 编译好的二进制
|
||
├── config/ # 配置文件
|
||
├── scripts/ # 部署脚本
|
||
│ ├── 3588admin # 统一管理脚本 ⭐
|
||
│ └── 3588admin.service # Systemd 服务文件
|
||
├── systemd/ # 服务文件
|
||
├── docs/ # 文档
|
||
├── VERSION # 版本信息
|
||
└── README-离线安装.txt # 快速安装指南
|
||
```
|
||
|
||
---
|
||
|
||
### 3588admin.service
|
||
|
||
**用途**: Systemd 服务配置文件
|
||
|
||
**使用方法**:
|
||
```bash
|
||
# 通常由 install 命令自动安装
|
||
# 如需手动安装:
|
||
sudo cp scripts/3588admin.service /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
|
||
# 管理服务
|
||
sudo systemctl start 3588admin # 启动
|
||
sudo systemctl stop 3588admin # 停止
|
||
sudo systemctl restart 3588admin # 重启
|
||
sudo systemctl status 3588admin # 查看状态
|
||
sudo systemctl enable 3588admin # 开机自启
|
||
sudo systemctl disable 3588admin # 禁用自启
|
||
```
|
||
|
||
---
|
||
|
||
## 典型使用场景
|
||
|
||
### 场景1: 首次部署
|
||
|
||
> **说明**: 以下流程在联网机器上构建部署包，然后拷贝到离线生产环境安装。目标机器**不需要** Go 运行时。
|
||
|
||
```bash
|
||
# ========== 在联网机器上（构建环境）==========
|
||
cd 3588AdminBackend/scripts/deploy
|
||
|
||
# 构建离线部署包（包含编译好的静态二进制文件）
|
||
./build-offline-package.sh
|
||
|
||
# 输出: build/3588AdminBackend-离线部署包-YYYYMMDD.tar.gz
|
||
|
||
# 复制到光盘/USB/ISO，然后挂载到生产服务器
|
||
|
||
# ========== 在生产服务器上（离线环境）==========
|
||
# 解压部署包
|
||
tar -xzf 3588AdminBackend-离线部署包-*.tar.gz
|
||
cd 3588AdminBackend-离线部署包-*/
|
||
|
||
# 检查环境（无需 Go 运行时）
|
||
sudo ./scripts/3588admin check
|
||
|
||
# 安装（无需 Go 运行时）
|
||
sudo ./scripts/3588admin install
|
||
|
||
# 修改配置
|
||
sudo nano /opt/3588admin/config/managerd.json
|
||
|
||
# 启动服务
|
||
sudo 3588admin start
|
||
sudo 3588admin status
|
||
```
|
||
|
||
### 场景2: 日常运维
|
||
|
||
```bash
|
||
# 查看状态
|
||
sudo 3588admin status
|
||
|
||
# 查看日志
|
||
tail -f /opt/3588admin/logs/managerd.log
|
||
|
||
# 重启服务
|
||
sudo 3588admin restart
|
||
|
||
# 或者使用 systemctl
|
||
sudo systemctl restart 3588admin
|
||
```
|
||
|
||
### 场景3: 版本升级
|
||
|
||
```bash
|
||
# 1. 在新的部署包中执行升级
|
||
sudo ./scripts/3588admin upgrade
|
||
|
||
# 2. 验证升级
|
||
sudo 3588admin status
|
||
|
||
# 3. 如出现问题，查看日志
|
||
tail -n 50 /opt/3588admin/logs/managerd.log
|
||
```
|
||
|
||
### 场景4: 修改配置
|
||
|
||
```bash
|
||
# 1. 停止服务
|
||
sudo 3588admin stop
|
||
|
||
# 2. 修改配置
|
||
sudo nano /opt/3588admin/config/managerd.json
|
||
|
||
# 3. 验证配置格式
|
||
python3 -m json.tool /opt/3588admin/config/managerd.json
|
||
|
||
# 4. 启动服务
|
||
sudo 3588admin start
|
||
```
|
||
|
||
### 场景5: 完全卸载
|
||
|
||
```bash
|
||
# 1. 备份配置（可选）
|
||
cp /opt/3588admin/config/managerd.json ~/managerd-backup.json
|
||
|
||
# 2. 执行卸载
|
||
sudo 3588admin uninstall
|
||
|
||
# 3. 确认删除
|
||
ls /opt/3588admin # 应提示不存在
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 执行脚本时提示 "Permission denied"
|
||
|
||
**解决**:
|
||
```bash
|
||
chmod +x scripts/3588admin
|
||
sudo ./scripts/3588admin install
|
||
```
|
||
|
||
### Q2: 安装后命令找不到（3588admin-start 等）
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查是否创建了快捷方式
|
||
ls -la /usr/local/bin/3588admin-*
|
||
|
||
# 如未创建，重新执行安装
|
||
sudo 3588admin install
|
||
|
||
# 或者使用完整路径
|
||
sudo /opt/3588admin/scripts/3588admin start
|
||
```
|
||
|
||
### Q3: 如何查看更详细的日志？
|
||
|
||
**解决**:
|
||
```bash
|
||
# 实时查看日志
|
||
tail -f /opt/3588admin/logs/managerd.log
|
||
|
||
# 查看最近100行
|
||
tail -n 100 /opt/3588admin/logs/managerd.log
|
||
|
||
# 搜索错误
|
||
grep -i error /opt/3588admin/logs/managerd.log
|
||
```
|
||
|
||
### Q4: 服务启动后立即退出
|
||
|
||
**排查**:
|
||
```bash
|
||
# 1. 查看日志
|
||
tail /opt/3588admin/logs/managerd.log
|
||
|
||
# 2. 检查配置格式
|
||
python3 -m json.tool /opt/3588admin/config/managerd.json
|
||
|
||
# 3. 检查端口占用
|
||
sudo netstat -tlnp | grep 18080
|
||
```
|
||
|
||
### Q5: 如何修改监听端口？
|
||
|
||
**解决**:
|
||
```bash
|
||
# 1. 停止服务
|
||
sudo 3588admin stop
|
||
|
||
# 2. 编辑配置
|
||
sudo nano /opt/3588admin/config/managerd.json
|
||
# 修改 "listen" 为 "127.0.0.1:18081" 或其他端口
|
||
|
||
# 3. 启动服务
|
||
sudo 3588admin start
|
||
```
|
||
|
||
---
|
||
|
||
## 文件说明
|
||
|
||
```
|
||
scripts/
|
||
├── deploy/ # 部署脚本目录
|
||
│ ├── Manual.md # 本文档
|
||
│ ├── 3588admin # 统一管理脚本 ⭐
|
||
│ ├── build-offline-package.sh # 构建离线包
|
||
│ └── 3588admin.service # Systemd服务
|
||
└── dev-run.sh # 开发运行脚本
|
||
```
|
||
|
||
---
|
||
|
||
**维护者**: 运维团队
|
||
**最后更新**: 2026-02-25
|
||
**版本**: 2.0 (整合版)
|