3588AdminBackend/docs/离线部署文档.md

3588AdminBackend 离线部署文档

目标环境: Ubuntu 22.04.5 LTS (离线环境，无法连接互联网)
部署方式: 在 Windows 上交叉编译，上传安装包到 Ubuntu 进行离线部署
版本: V2.1 (Windows 构建版)

---

目录

1. 部署概述
2. 准备环境（Windows）
3. 构建步骤（Windows）
4. 离线安装（Ubuntu）
5. 验证与启动
6. 常见问题排查

---

1. 部署概述

1.1 项目简介

3588AdminBackend 是 Orange Pi 3588 媒体服务器的后台管理端，提供以下功能：

• 设备发现与注册管理
• 设备配置下发与批量任务管理
• 代理调用设备端 API
• SSE 实时任务进度推送

1.2 技术栈

组件	版本	说明
Go	1.23+	编译环境（仅 Windows 构建机需要）
chi	v5.2.3	Web 框架（已静态编译到二进制）
cors	v1.2.2	CORS 中间件（已静态编译到二进制）
uuid	v1.6.0	UUID 生成库（已静态编译到二进制）

注意: Go 编译生成的是静态链接的二进制文件，目标机器（Ubuntu 生产环境）不需要安装 Go 运行时，只需要 Linux 内核即可运行。

1.3 部署流程概览

┌──────────────────────────────────────────────────────────────────────┐
│                         Windows（构建环境）                           │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │ 1. 安装 Go 1.23+                                             │   │
│  │ 2. 运行 build-windows.ps1                                    │   │
│  │ 3. 生成 3588AdminBackend-离线部署包-YYYYMMDD.tar.gz         │   │
│  └──────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼ (上传到 Ubuntu 服务器)
┌──────────────────────────────────────────────────────────────────────┐
│                       Ubuntu（生产环境）                              │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  无需 Go 运行时！直接运行编译好的静态二进制文件               │   │
│  │  - tar -xzf 3588AdminBackend-离线部署包-*.tar.gz            │   │
│  │  - sudo ./scripts/3588admin install                          │   │
│  │  - sudo ./scripts/3588admin start                            │   │
│  └──────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

---

2. 准备环境（Windows）

2.1 系统要求

• 操作系统: Windows 10/11 或 Windows Server 2019+
• 磁盘空间: 至少 1GB 可用空间
• Go 版本: 1.23.3 或更高
• 网络: 可访问互联网（下载 Go 依赖）

2.2 安装 Go 编译环境

1. 下载 Go 安装包

   • 访问 https://go.dev/dl/
   • 下载 go1.23.3.windows-amd64.msi

2. 安装 Go

   • 双击 MSI 文件，按向导安装
   • 默认安装到 C:\Program Files\Go\
   • 安装程序会自动配置 PATH

3. 验证安装

   # 打开 PowerShell 或 CMD
   go version
   # 输出: go version go1.23.3 windows/amd64
   

2.3 准备项目源码

将项目源码复制到 Windows 机器上，例如：

C:\Users\YourName\3588AdminBackend\

目录结构应包含：

3588AdminBackend/
├── cmd/
│   └── managerd/
├── internal/
├── scripts/
│   └── deploy/
│       ├── 3588admin              # 管理脚本
│       ├── 3588admin.service      # Systemd 服务
│       └── build-windows.ps1      # Windows 构建脚本
├── templates/
├── go.mod
└── go.sum

---

3. 构建步骤（Windows）

3.1 运行构建脚本

打开 PowerShell，进入项目目录：

# 进入项目目录
cd C:\Users\YourName\3588AdminBackend\scripts\deploy

# 执行构建脚本
.\build-windows.ps1

或一行命令：

& "C:<Users>YourName<3588AdminBackend<scripts>deploy<build-windows.ps1"

3.2 构建输出

构建完成后，会在 build\ 目录下生成：

3588AdminBackend-离线部署包-YYYYMMDD.tar.gz

构建输出示例：

========== 3588AdminBackend Windows 构建 ==========
项目目录: C:<Users>YourName<3588AdminBackend
构建目录: C:<Users>YourName<3588AdminBackend<build
Go 版本: go version go1.23.3 windows/amd64

[1/6] 清理旧构建...
[2/6] 创建目录结构...
[3/6] 交叉编译 Linux AMD64 版本...
  编译成功
[4/6] 复制配置文件...
[5/6] 复制部署脚本...
[6/6] 复制文档...

打包...

========== 构建完成 ==========

输出文件:
  3588AdminBackend-离线部署包-20260225.tar.gz (12.34 MB)

部署包位置: C:<Users>YourName<3588AdminBackend<build<3588AdminBackend-离线部署包-20260225.tar.gz

使用说明:
1. 将 3588AdminBackend-离线部署包-20260225.tar.gz 上传到 Ubuntu 服务器
2. 解压并运行: sudo ./scripts/3588admin install

3.3 手动打包（如不使用脚本）

如果 PowerShell 脚本执行失败，可以手动操作：

# 1. 进入项目目录
cd C:<Users>YourName<3588AdminBackend

# 2. 交叉编译 Linux 版本
$env:GOOS = "linux"
$env:GOARCH = "amd64"
go build -ldflags="-s -w" -o managerd-linux-amd64 .\cmd\managerd

# 3. 创建部署目录
mkdir build<3588admin-deploy<bin
mkdir build<3588admin-deploy<config
mkdir build<3588admin-deploy<scripts

# 4. 复制文件
copy managerd-linux-amd64 build<3588admin-deploy<bin<managerd
copy scripts>deploy<3588admin build<3588admin-deploy<scripts<
copy scripts>deploy<3588admin.service build<3588admin-deploy<scripts<
copy managerd.json build<3588admin-deploy<config<managerd.json.example

# 5. 打包
cd build
tar -czf 3588AdminBackend-离线部署包-$(Get-Date -Format 'yyyyMMdd').tar.gz 3588admin-deploy<

3.4 上传到 Ubuntu 服务器

使用 SCP、FTP 或任何文件传输工具将部署包上传到 Ubuntu：

# 使用 scp（如果 Windows 有 OpenSSH）
scp .\build<3588AdminBackend-离线部署包-*.tar.gz user@ubuntu-server:/tmp/

# 或使用 WinSCP、FileZilla 等图形化工具

---

4. 离线安装（Ubuntu）

环境: Ubuntu 22.04.5 LTS，无网络连接

4.1 解压部署包

# 进入上传目录
cd /tmp

# 解压
tar -xzf 3588AdminBackend-离线部署包-*.tar.gz

# 进入部署目录
cd 3588AdminBackend-离线部署包-*/

# 查看内容
ls -la

4.2 执行安装

# 检查环境（可选但推荐）
sudo ./scripts/3588admin check

# 执行安装
sudo ./scripts/3588admin install

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

安装脚本会自动完成：

• 检查 root 权限
• 复制文件到安装目录
• 设置执行权限
• 创建配置文件
• 创建命令快捷方式（3588admin-start, 3588admin-stop, 3588admin-status）
• 安装 Systemd 服务（可选）

4.3 配置 Systemd 服务（可选但推荐）

# 复制服务文件
sudo cp /opt/3588admin/scripts/3588admin.service /etc/systemd/system/

# 重新加载 systemd
sudo systemctl daemon-reload

# 设置开机自启
sudo systemctl enable 3588admin

# 启动服务
sudo systemctl start 3588admin

# 查看状态
sudo systemctl status 3588admin

---

5. 验证与启动

5.1 修改配置文件

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

关键配置项说明：

{
  "listen": "0.0.0.0:18080",       // HTTP API 监听地址（0.0.0.0 允许外部访问）
  "discovery_port": 35688,           // UDP 发现端口
  "discovery_timeout_ms": 1200,      // 发现超时时间
  "offline_after_ms": 10000,         // 设备离线判定时间
  "agent_token": "CHANGE_ME",        // !!! 必须修改 !!! 与设备端通信的 Token
  "concurrency": 5                   // 批量任务并发数
}

配置建议：

• listen: 如果前端通过本地访问，保持 127.0.0.1:18080；如果需要外部访问，改为 0.0.0.0:18080
• agent_token: 必须修改为安全的随机字符串，与设备端配置的 token 保持一致

5.2 启动服务

方式1: 使用管理脚本（推荐）

# 启动
sudo 3588admin start

# 查看状态
sudo 3588admin status

# 停止
sudo 3588admin stop

# 重启
sudo 3588admin restart

方式2: 使用快捷命令

# 启动
sudo 3588admin-start

# 查看状态
sudo 3588admin-status

# 停止
sudo 3588admin-stop

方式3: 使用 Systemd

sudo systemctl start 3588admin
sudo systemctl status 3588admin

5.3 验证服务

# 检查进程
ps aux | grep managerd

# 检查端口监听
sudo netstat -tlnp | grep 18080
# 或
sudo ss -tlnp | grep 18080

# 测试 API
curl http://127.0.0.1:18080/api/devices

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

5.4 防火墙配置

# 开放 HTTP API 端口（如需外部访问）
sudo ufw allow 18080/tcp

# 开放 UDP 发现端口（必须）
sudo ufw allow 35688/udp

# 重新加载防火墙
sudo ufw reload

---

6. 常见问题排查

6.1 Windows 构建失败

问题: 执行 build-windows.ps1 提示权限不足

解决:

# 以管理员身份运行 PowerShell
# 右键点击 PowerShell -> 以管理员身份运行

# 或修改执行策略（临时）
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
.\build-windows.ps1

问题: tar 命令不存在

解决: Windows 10/11 内置 tar，如果找不到，使用 7-Zip 或其他工具手动打包。

6.2 Ubuntu 上启动失败

问题: 执行 start 命令提示启动失败

排查步骤:

# 1. 检查二进制文件架构是否匹配
file /opt/3588admin/bin/managerd
# 应输出: ELF 64-bit LSB executable, x86-64

# 2. 直接运行查看错误信息
/opt/3588admin/bin/managerd -config /opt/3588admin/config/managerd.json

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

6.3 端口被占用

问题: 提示端口 18080 已被占用

解决:

# 查找占用端口的进程
sudo lsof -i :18080
# 或
sudo netstat -tlnp | grep 18080

# 修改配置文件使用其他端口
sudo nano /opt/3588admin/config/managerd.json
# 修改 "listen" 为 "127.0.0.1:18081" 或其他端口

6.4 无法发现设备

问题: 设备发现功能不工作

排查:

# 检查 UDP 端口监听
sudo netstat -ulnp | grep 35688

# 检查防火墙
sudo ufw status | grep 35688

# 检查网络接口是否有权限发送广播
# 可能需要以 root 运行

# 检查设备端是否配置了正确的发现端口和 token

6.5 权限问题

问题: 提示 Permission denied

解决:

# 修复权限
sudo chmod +x /opt/3588admin/bin/managerd
sudo chmod +x /opt/3588admin/scripts/3588admin

# 确保以 root 运行
sudo 3588admin start

6.6 日志查看

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

# 查看最近 100 行
tail -n 100 /opt/3588admin/logs/managerd.log

# 搜索错误信息
grep -i error /opt/3588admin/logs/managerd.log

---

附录

A. 目录结构参考

Windows 构建机：

C:<Users>YourName<3588AdminBackend<
├── build<                                          # 构建输出
│   └── 3588AdminBackend-离线部署包-20260225<
│       ├── bin<
│       │   └── managerd                           # Linux 静态二进制文件
│       ├── config<
│       ├── scripts<
│       │   └── 3588admin                          # 管理脚本
│       ├── docs<
│       └── README-离线安装.txt
├── scripts>deploy<
│   ├── 3588admin
│   ├── 3588admin.service
│   └── build-windows.ps1                          # Windows 构建脚本
├── cmd<
├── internal<
└── go.mod

Ubuntu 生产环境：

/opt/3588admin/
├── bin/
│   └── managerd                    # 主程序（Windows 交叉编译生成）
├── config/
│   └── managerd.json               # 配置文件
├── logs/
│   └── managerd.log                # 运行日志
├── scripts/
│   ├── 3588admin                   # 统一管理脚本
│   └── 3588admin.service           # 服务文件（复制用）
└── systemd/                        # （如安装服务）

B. 管理脚本命令速查

# 环境检查
sudo 3588admin check

# 安装
sudo 3588admin install [目录]

# 启动/停止/重启
sudo 3588admin start
sudo 3588admin stop
sudo 3588admin restart

# 查看状态
sudo 3588admin status

# 升级
sudo 3588admin upgrade [目录]

# 卸载
sudo 3588admin uninstall [目录]

# 帮助
3588admin help

C. 升级步骤

# 1. 停止服务
sudo 3588admin stop
# 或
sudo systemctl stop 3588admin

# 2. 备份配置
cp /opt/3588admin/config/managerd.json ~/managerd.json.bak

# 3. 在 Windows 上重新构建新版本
# 运行 build-windows.ps1

# 4. 上传到 Ubuntu 并执行升级
sudo ./scripts/3588admin upgrade

# 5. 验证升级
sudo 3588admin status

D. 完全卸载

# 方式1: 使用管理脚本
sudo 3588admin uninstall

# 方式2: 手动卸载
sudo 3588admin stop
sudo systemctl stop 3588admin 2>/dev/null || true
sudo systemctl disable 3588admin 2>/dev/null || true
sudo rm -f /etc/systemd/system/3588admin.service
sudo rm -rf /opt/3588admin
sudo rm -f /usr/local/bin/3588admin*
sudo systemctl daemon-reload

echo "卸载完成"

---

文档版本: 2.1 (Windows 构建版)
最后更新: 2026-02-25
适用版本: 3588AdminBackend V1.0+