Doni/3588AdminBackend
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
5fefa8a154
3588AdminBackend/scripts/deploy/Manual.md
tian 5fefa8a154 完善安装脚本和文档
2026-02-25 16:32:38 +08:00

11 KiB
Raw Blame History

3588AdminBackend 部署脚本使用说明

本目录包含 3588AdminBackend 的统一管理脚本，支持离线环境下的安装、升级、卸载和日常运维。

目录

  1. 快速开始
  2. 脚本清单
  3. 详细使用指南
  4. 典型使用场景
  5. 常见问题

快速开始

第一次部署（离线环境）

# 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 是统一的管理脚本，整合了过去分散的多个脚本功能。

命令概览

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 - 安装服务

语法:

sudo 3588admin install [安装目录]

参数:

  • 安装目录: 可选，默认为 /opt/3588admin

使用方法:

# 默认安装到 /opt/3588admin
sudo ./scripts/3588admin install

# 自定义安装目录
sudo ./scripts/3588admin install /usr/local/3588admin

安装流程:

  1. 检查 root 权限
  2. 安装依赖包（如有）
  3. 创建安装目录
  4. 复制二进制文件、配置、脚本
  5. 设置执行权限
  6. 创建命令快捷方式（3588admin-start 等）
  7. 安装 Systemd 服务（可选）

安装后操作:

# 编辑配置文件
sudo nano /opt/3588admin/config/managerd.json

# 特别注意修改:
# - agent_token: 改为安全的随机字符串
# - listen: 如需外部访问改为 "0.0.0.0:18080"

status - 查看状态

使用方法:

# 方式1: 使用快捷命令（推荐）
sudo 3588admin-status

# 方式2: 直接执行
sudo 3588admin status

显示内容:

  • 基本信息（目录、配置文件路径）
  • 二进制文件状态
  • 配置文件内容和监听地址
  • 进程状态（运行/停止）
  • CPU/内存使用情况
  • 网络端口监听状态
  • HTTP API 连通性测试
  • 最新日志

start - 启动服务

使用方法:

# 方式1: 使用快捷命令（推荐）
sudo 3588admin-start

# 方式2: 直接执行
sudo 3588admin start

功能:

  • 检查配置文件是否存在且格式正确
  • 检查服务是否已在运行
  • 后台启动服务并记录 PID
  • 显示启动结果

stop - 停止服务

使用方法:

# 方式1: 使用快捷命令（推荐）
sudo 3588admin-stop

# 方式2: 直接执行
sudo 3588admin stop

功能:

  • 优雅停止（发送 SIGTERM，等待最多 10 秒）
  • 强制结束（如优雅停止失败）
  • 清理 PID 文件

restart - 重启服务

使用方法:

sudo 3588admin restart

upgrade - 升级服务

用途: 升级到新版本（保留配置）

语法:

sudo 3588admin upgrade [安装目录]

参数:

  • 安装目录: 可选，默认为 /opt/3588admin

使用方法:

# 升级流程
# 1. 停止服务
# 2. 备份现有数据和配置
# 3. 更新二进制文件
# 4. 更新脚本
# 5. 启动服务

sudo ./scripts/3588admin upgrade

升级前准备:

  1. 在新的部署包中确认 bin/managerd 是新版本
  2. 执行升级命令

回滚方法:

# 如升级后有问题，快速回滚
sudo 3588admin stop
sudo cp /root/3588admin-backup-xxx/managerd.old /opt/3588admin/bin/managerd
sudo 3588admin start

uninstall - 卸载服务

用途: 完全卸载 3588AdminBackend

语法:

sudo 3588admin uninstall [安装目录]

参数:

  • 安装目录: 可选，默认为 /opt/3588admin

使用方法:

# 默认卸载
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）
  • 防火墙配置
  • 磁盘空间
  • 必要工具

使用方法:

# 安装前检查
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+ 已安装
  • 项目源码完整

使用方法:

# 在项目目录下执行
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 服务配置文件

使用方法:

# 通常由 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 运行时。

# ========== 在联网机器上（构建环境）==========
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: 日常运维

# 查看状态
sudo 3588admin status

# 查看日志
tail -f /opt/3588admin/logs/managerd.log

# 重启服务
sudo 3588admin restart

# 或者使用 systemctl
sudo systemctl restart 3588admin

场景3: 版本升级

# 1. 在新的部署包中执行升级
sudo ./scripts/3588admin upgrade

# 2. 验证升级
sudo 3588admin status

# 3. 如出现问题，查看日志
tail -n 50 /opt/3588admin/logs/managerd.log

场景4: 修改配置

# 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: 完全卸载

# 1. 备份配置（可选）
cp /opt/3588admin/config/managerd.json ~/managerd-backup.json

# 2. 执行卸载
sudo 3588admin uninstall

# 3. 确认删除
ls /opt/3588admin  # 应提示不存在

常见问题

Q1: 执行脚本时提示 "Permission denied"

解决:

chmod +x scripts/3588admin
sudo ./scripts/3588admin install

Q2: 安装后命令找不到（3588admin-start 等）

解决:

# 检查是否创建了快捷方式
ls -la /usr/local/bin/3588admin-*

# 如未创建，重新执行安装
sudo 3588admin install

# 或者使用完整路径
sudo /opt/3588admin/scripts/3588admin start

Q3: 如何查看更详细的日志？

解决:

# 实时查看日志
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: 服务启动后立即退出

排查:

# 1. 查看日志
tail /opt/3588admin/logs/managerd.log

# 2. 检查配置格式
python3 -m json.tool /opt/3588admin/config/managerd.json

# 3. 检查端口占用
sudo netstat -tlnp | grep 18080

Q5: 如何修改监听端口？

解决:

# 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 (整合版)