dekun
196 lines
4.7 KiB
Markdown
196 lines
4.7 KiB
Markdown
# 部署文档
|
||
|
||
本文说明如何在 **Ubuntu** 服务器上将 K 线点位标注工具部署到 **`/opt/chart-label-tool`**，使用 **Python 虚拟环境** 托管静态文件，并由 **PM2** 守护进程，在 **局域网** 内访问。
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 要求 |
|
||
|------|------|
|
||
| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04（推荐） |
|
||
| 权限 | root 或 sudo |
|
||
| 网络 | 可访问 git 仓库；客户端与服务器在同一局域网 |
|
||
| 浏览器 | Chrome / Edge 等现代浏览器 |
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
浏览器 (局域网)
|
||
↓ HTTP :8010
|
||
PM2 → Python venv → http.server
|
||
↓ 静态文件
|
||
/opt/chart-label-tool/public/
|
||
```
|
||
|
||
- 无后端业务逻辑，仅静态资源服务
|
||
- 标注数据全部在用户浏览器内存中处理，不上传服务器
|
||
|
||
## 方式一：一键部署（推荐）
|
||
|
||
在**已能访问 Git 仓库**的 Ubuntu 机器上执行：
|
||
|
||
```bash
|
||
# 若目录不存在，先克隆
|
||
sudo git clone https://git.bz121.com/dekun/chart-label-tool.git /opt/chart-label-tool
|
||
|
||
cd /opt/chart-label-tool
|
||
sudo bash deploy/install.sh
|
||
```
|
||
|
||
脚本将自动完成：
|
||
|
||
1. 安装 `git`、`python3`、`python3-venv`
|
||
2. 安装 Node.js 与 PM2（若未安装）
|
||
3. 克隆/更新代码到 `/opt/chart-label-tool`
|
||
4. 创建 Python 虚拟环境 `venv/`
|
||
5. 使用 PM2 启动 `chart-label-tool` 进程（监听 `0.0.0.0:8010`）
|
||
6. 执行 `pm2 save` 与 `pm2 startup`（开机自启）
|
||
|
||
部署成功后，在局域网内任意电脑浏览器访问：
|
||
|
||
```text
|
||
http://<服务器局域网IP>:8010
|
||
```
|
||
|
||
查看本机 IP：
|
||
|
||
```bash
|
||
hostname -I
|
||
# 或
|
||
ip addr show | grep "inet "
|
||
```
|
||
|
||
## 方式二：手动部署
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
sudo apt-get update
|
||
sudo apt-get install -y git python3 python3-venv curl
|
||
|
||
# 安装 Node.js 20 与 PM2
|
||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
sudo npm install -g pm2
|
||
```
|
||
|
||
### 2. 克隆项目
|
||
|
||
```bash
|
||
sudo mkdir -p /opt
|
||
sudo git clone https://git.bz121.com/dekun/chart-label-tool.git /opt/chart-label-tool
|
||
cd /opt/chart-label-tool
|
||
```
|
||
|
||
### 3. 创建虚拟环境
|
||
|
||
```bash
|
||
sudo python3 -m venv /opt/chart-label-tool/venv
|
||
```
|
||
|
||
> 本项目不依赖第三方 pip 包，`http.server` 来自 Python 标准库。
|
||
|
||
### 4. 启动 PM2
|
||
|
||
```bash
|
||
cd /opt/chart-label-tool
|
||
sudo pm2 start deploy/ecosystem.config.cjs
|
||
sudo pm2 save
|
||
sudo pm2 startup
|
||
```
|
||
|
||
按 `pm2 startup` 提示执行生成的 `sudo env PATH=...` 命令。
|
||
|
||
### 5. 验证
|
||
|
||
```bash
|
||
pm2 status
|
||
curl -I http://127.0.0.1:8010
|
||
```
|
||
|
||
浏览器打开 `http://<服务器IP>:8010`，应能看到标注工具页面。
|
||
|
||
## 防火墙
|
||
|
||
若启用了 UFW，需放行 8010 端口：
|
||
|
||
```bash
|
||
sudo ufw allow 8010/tcp
|
||
sudo ufw reload
|
||
```
|
||
|
||
## 常用运维命令
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 查看状态 | `pm2 status` |
|
||
| 查看日志 | `pm2 logs chart-label-tool` |
|
||
| 重启服务 | `pm2 restart chart-label-tool` |
|
||
| 停止服务 | `pm2 stop chart-label-tool` |
|
||
| 更新代码 | `cd /opt/chart-label-tool && sudo git pull && sudo pm2 restart chart-label-tool` |
|
||
|
||
## 修改端口
|
||
|
||
编辑 `deploy/ecosystem.config.cjs` 中 `args` 里的端口号，例如改为 `9000`：
|
||
|
||
```javascript
|
||
args: "-m http.server 9000 --bind 0.0.0.0 --directory /opt/chart-label-tool/public",
|
||
```
|
||
|
||
然后执行：
|
||
|
||
```bash
|
||
pm2 restart chart-label-tool
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### `install.sh: $'\r': command not found`
|
||
|
||
脚本在 Windows 下编辑后可能带 **CRLF** 换行，Linux 无法执行。任选一种修复：
|
||
|
||
```bash
|
||
# 方式一：去掉回车符后重新执行
|
||
sed -i 's/\r$//' /opt/chart-label-tool/deploy/install.sh
|
||
sudo bash /opt/chart-label-tool/deploy/install.sh
|
||
|
||
# 方式二：拉取已修复的仓库（含 .gitattributes 强制 LF）
|
||
cd /opt/chart-label-tool && git pull
|
||
sed -i 's/\r$//' deploy/install.sh
|
||
sudo bash deploy/install.sh
|
||
```
|
||
|
||
### 页面无法打开
|
||
|
||
1. `pm2 status` 确认进程为 `online`
|
||
2. `ss -tlnp | grep 8010` 确认端口在监听
|
||
3. 检查服务器与客户端是否同一局域网
|
||
4. 检查防火墙是否放行 8010
|
||
|
||
### PM2 启动失败
|
||
|
||
```bash
|
||
pm2 logs chart-label-tool --lines 50
|
||
```
|
||
|
||
确认虚拟环境存在：
|
||
|
||
```bash
|
||
ls -la /opt/chart-label-tool/venv/bin/python
|
||
```
|
||
|
||
手动测试：
|
||
|
||
```bash
|
||
/opt/chart-label-tool/venv/bin/python -m http.server 8010 --bind 0.0.0.0 --directory /opt/chart-label-tool/public
|
||
```
|
||
|
||
### Git 拉取失败
|
||
|
||
检查仓库地址与凭据，或先在能访问的机器上打包上传到服务器。
|
||
|
||
## 安全说明
|
||
|
||
- 本工具为**内网静态站点**，请勿直接暴露到公网
|
||
- 用户标注数据不经过服务器存储；服务器仅提供 HTML/JS/CSS 文件
|
||
- 若需 HTTPS，可在前方增加 Nginx 反向代理并配置证书
|