tian
46f264d4d4
- Rename binary: managerd → safesightd - Rename config: managerd.json → safesightd.json - Update Go module: 3588AdminBackend → safesight-control - Update all import paths and references - Rename scripts and deploy files
593 lines
15 KiB
Markdown
593 lines
15 KiB
Markdown
# SafeSight Control 离线部署文档
|
||
|
||
> **目标环境**: 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 项目简介
|
||
|
||
SafeSight Control 是 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. 生成 SafeSight Control-离线部署包-YYYYMMDD.tar.gz │ │
|
||
│ └──────────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼ (上传到 Ubuntu 服务器)
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ Ubuntu（生产环境） │
|
||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||
│ │ 无需 Go 运行时！直接运行编译好的静态二进制文件 │ │
|
||
│ │ - tar -xzf SafeSight Control-离线部署包-*.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\SafeSight Control\
|
||
```
|
||
|
||
目录结构应包含：
|
||
```
|
||
SafeSight Control/
|
||
├── cmd/
|
||
│ └── safesightd/
|
||
├── 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\SafeSight Control\scripts\deploy
|
||
|
||
# 执行构建脚本
|
||
.\build-windows.ps1
|
||
```
|
||
|
||
或一行命令：
|
||
```powershell
|
||
& "C:<Users>YourName<SafeSight Control<scripts>deploy<build-windows.ps1"
|
||
```
|
||
|
||
### 3.2 构建输出
|
||
|
||
构建完成后，会在 `build\` 目录下生成：
|
||
```
|
||
SafeSight Control-离线部署包-YYYYMMDD.tar.gz
|
||
```
|
||
|
||
构建输出示例：
|
||
```
|
||
========== SafeSight Control Windows 构建 ==========
|
||
项目目录: C:<Users>YourName<SafeSight Control
|
||
构建目录: C:<Users>YourName<SafeSight Control<build
|
||
Go 版本: go version go1.23.3 windows/amd64
|
||
|
||
[1/6] 清理旧构建...
|
||
[2/6] 创建目录结构...
|
||
[3/6] 交叉编译 Linux AMD64 版本...
|
||
编译成功
|
||
[4/6] 复制配置文件...
|
||
[5/6] 复制部署脚本...
|
||
[6/6] 复制文档...
|
||
|
||
打包...
|
||
|
||
========== 构建完成 ==========
|
||
|
||
输出文件:
|
||
SafeSight Control-离线部署包-20260225.tar.gz (12.34 MB)
|
||
|
||
部署包位置: C:<Users>YourName<SafeSight Control<build<SafeSight Control-离线部署包-20260225.tar.gz
|
||
|
||
使用说明:
|
||
1. 将 SafeSight Control-离线部署包-20260225.tar.gz 上传到 Ubuntu 服务器
|
||
2. 解压并运行: sudo ./scripts/3588admin install
|
||
```
|
||
|
||
### 3.3 手动打包（如不使用脚本）
|
||
|
||
如果 PowerShell 脚本执行失败，可以手动操作：
|
||
|
||
```powershell
|
||
# 1. 进入项目目录
|
||
cd C:<Users>YourName<SafeSight Control
|
||
|
||
# 2. 交叉编译 Linux 版本
|
||
$env:GOOS = "linux"
|
||
$env:GOARCH = "amd64"
|
||
go build -ldflags="-s -w" -o safesightd-linux-amd64 .\cmd\safesightd
|
||
|
||
# 3. 创建部署目录
|
||
mkdir build<3588admin-deploy<bin
|
||
mkdir build<3588admin-deploy<config
|
||
mkdir build<3588admin-deploy<scripts
|
||
|
||
# 4. 复制文件
|
||
copy safesightd-linux-amd64 build<3588admin-deploy<bin<safesightd
|
||
copy scripts>deploy<3588admin build<3588admin-deploy<scripts<
|
||
copy scripts>deploy<3588admin.service build<3588admin-deploy<scripts<
|
||
copy safesightd.json build<3588admin-deploy<config<safesightd.json.example
|
||
|
||
# 5. 打包
|
||
cd build
|
||
tar -czf SafeSight Control-离线部署包-$(Get-Date -Format 'yyyyMMdd').tar.gz 3588admin-deploy<
|
||
```
|
||
|
||
### 3.4 上传到 Ubuntu 服务器
|
||
|
||
使用 SCP、FTP 或任何文件传输工具将部署包上传到 Ubuntu：
|
||
|
||
```powershell
|
||
# 使用 scp（如果 Windows 有 OpenSSH）
|
||
scp .\build<SafeSight Control-离线部署包-*.tar.gz user@ubuntu-server:/tmp/
|
||
|
||
# 或使用 WinSCP、FileZilla 等图形化工具
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 离线安装（Ubuntu）
|
||
|
||
> **环境**: Ubuntu 22.04.5 LTS，无网络连接
|
||
|
||
### 4.1 解压部署包
|
||
|
||
```bash
|
||
# 进入上传目录
|
||
cd /tmp
|
||
|
||
# 解压
|
||
tar -xzf SafeSight Control-离线部署包-*.tar.gz
|
||
|
||
# 进入部署目录
|
||
cd SafeSight Control-离线部署包-*/
|
||
|
||
# 查看内容
|
||
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/safesightd.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 safesightd
|
||
|
||
# 检查端口监听
|
||
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/safesightd.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/safesightd
|
||
# 应输出: ELF 64-bit LSB executable, x86-64
|
||
|
||
# 2. 直接运行查看错误信息
|
||
/opt/3588admin/bin/safesightd -config /opt/3588admin/config/safesightd.json
|
||
|
||
# 3. 检查配置文件格式
|
||
python3 -m json.tool /opt/3588admin/config/safesightd.json
|
||
```
|
||
|
||
### 6.3 端口被占用
|
||
|
||
**问题**: 提示端口 18080 已被占用
|
||
|
||
**解决**:
|
||
|
||
```bash
|
||
# 查找占用端口的进程
|
||
sudo lsof -i :18080
|
||
# 或
|
||
sudo netstat -tlnp | grep 18080
|
||
|
||
# 修改配置文件使用其他端口
|
||
sudo nano /opt/3588admin/config/safesightd.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/safesightd
|
||
sudo chmod +x /opt/3588admin/scripts/3588admin
|
||
|
||
# 确保以 root 运行
|
||
sudo 3588admin start
|
||
```
|
||
|
||
### 6.6 日志查看
|
||
|
||
```bash
|
||
# 实时查看日志
|
||
tail -f /opt/3588admin/logs/safesightd.log
|
||
|
||
# 查看最近 100 行
|
||
tail -n 100 /opt/3588admin/logs/safesightd.log
|
||
|
||
# 搜索错误信息
|
||
grep -i error /opt/3588admin/logs/safesightd.log
|
||
```
|
||
|
||
---
|
||
|
||
## 附录
|
||
|
||
### A. 目录结构参考
|
||
|
||
**Windows 构建机**：
|
||
```
|
||
C:<Users>YourName<SafeSight Control<
|
||
├── build< # 构建输出
|
||
│ └── SafeSight Control-离线部署包-20260225<
|
||
│ ├── bin<
|
||
│ │ └── safesightd # Linux 静态二进制文件
|
||
│ ├── config<
|
||
│ ├── scripts<
|
||
│ │ └── 3588admin # 管理脚本
|
||
│ ├── docs<
|
||
│ └── README-离线安装.txt
|
||
├── scripts>deploy<
|
||
│ ├── 3588admin
|
||
│ ├── 3588admin.service
|
||
│ └── build-windows.ps1 # Windows 构建脚本
|
||
├── cmd<
|
||
├── internal<
|
||
└── go.mod
|
||
```
|
||
|
||
**Ubuntu 生产环境**：
|
||
```
|
||
/opt/3588admin/
|
||
├── bin/
|
||
│ └── safesightd # 主程序（Windows 交叉编译生成）
|
||
├── config/
|
||
│ └── safesightd.json # 配置文件
|
||
├── logs/
|
||
│ └── safesightd.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/safesightd.json ~/safesightd.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
|
||
**适用版本**: SafeSight Control V1.0+
|