# 3588AdminBackend 离线部署文档

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

---

## 目录

1. [部署概述](#1-部署概述)
2. [准备环境（Windows）](#2-准备环境windows)
3. [构建步骤（Windows）](#3-构建步骤windows)
4. [离线安装（Ubuntu）](#4-离线安装ubuntu)
5. [验证与启动](#5-验证与启动)
6. [常见问题排查](#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
   # 打开 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，进入项目目录：

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

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

或一行命令：
```powershell
& "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 脚本执行失败，可以手动操作：

```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：

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

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

---

## 4. 离线安装（Ubuntu）

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

### 4.1 解压部署包

```bash
# 进入上传目录
cd /tmp

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

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

# 查看内容
ls -la
```

### 4.2 执行安装

```bash
# 检查环境（可选但推荐）
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 服务（可选但推荐）

```bash
# 复制服务文件
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 修改配置文件

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

**关键配置项说明**：

```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: 使用管理脚本（推荐）**

```bash
# 启动
sudo 3588admin start

# 查看状态
sudo 3588admin status

# 停止
sudo 3588admin stop

# 重启
sudo 3588admin restart
```

**方式2: 使用快捷命令**

```bash
# 启动
sudo 3588admin-start

# 查看状态
sudo 3588admin-status

# 停止
sudo 3588admin-stop
```

**方式3: 使用 Systemd**

```bash
sudo systemctl start 3588admin
sudo systemctl status 3588admin
```

### 5.3 验证服务

```bash
# 检查进程
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 防火墙配置

```bash
# 开放 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
# 右键点击 PowerShell -> 以管理员身份运行

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

**问题**: `tar` 命令不存在

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

### 6.2 Ubuntu 上启动失败

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

**排查步骤**:

```bash
# 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 已被占用

**解决**:

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

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

### 6.4 无法发现设备

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

**排查**:

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

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

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

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

### 6.5 权限问题

**问题**: 提示 Permission denied

**解决**:

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

# 确保以 root 运行
sudo 3588admin start
```

### 6.6 日志查看

```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
```

---

## 附录

### 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. 管理脚本命令速查

```bash
# 环境检查
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. 升级步骤

```bash
# 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. 完全卸载

```bash
# 方式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+