# 部署文档

本文说明如何在 **Ubuntu** 服务器上将 K 线点位标注工具部署到 **`/opt/chart-label-tool`**，使用 **Python 虚拟环境** 托管静态文件，并由 **PM2** 守护进程，在 **局域网** 内访问。

## 环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04（推荐） |
| 权限 | root 或 sudo |
| 网络 | 可访问 git 仓库；客户端与服务器在同一局域网 |
| 浏览器 | Chrome / Edge 等现代浏览器 |

## 架构说明

```
浏览器 (局域网)
    ↓ HTTP :8080
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:8080`）
6. 执行 `pm2 save` 与 `pm2 startup`（开机自启）

部署成功后，在局域网内任意电脑浏览器访问：

```text
http://<服务器局域网IP>:8080
```

查看本机 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:8080
```

浏览器打开 `http://<服务器IP>:8080`，应能看到标注工具页面。

## 防火墙

若启用了 UFW，需放行 8080 端口：

```bash
sudo ufw allow 8080/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
```

## 故障排查

### 页面无法打开

1. `pm2 status` 确认进程为 `online`
2. `ss -tlnp | grep 8080` 确认端口在监听
3. 检查服务器与客户端是否同一局域网
4. 检查防火墙是否放行 8080

### 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 8080 --bind 0.0.0.0 --directory /opt/chart-label-tool/public
```

### Git 拉取失败

检查仓库地址与凭据，或先在能访问的机器上打包上传到服务器。

## 安全说明

- 本工具为**内网静态站点**，请勿直接暴露到公网
- 用户标注数据不经过服务器存储；服务器仅提供 HTML/JS/CSS 文件
- 若需 HTTPS，可在前方增加 Nginx 反向代理并配置证书