feat: K线点位标注工具完整实现与Ubuntu PM2部署
纯前端 Canvas 画线、拖拽、导出；Python venv + PM2 静态服务； 含部署脚本与使用/部署文档。 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
+180
@@ -0,0 +1,180 @@
|
||||
# 部署文档
|
||||
|
||||
本文说明如何在 **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 反向代理并配置证书
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
# 使用说明
|
||||
|
||||
## 访问地址
|
||||
|
||||
- **局域网部署**：`http://<服务器IP>:8080`
|
||||
- **本机调试**：`http://localhost:8080`
|
||||
|
||||
推荐使用 **Chrome** 或 **Edge** 浏览器。
|
||||
|
||||
## 界面布局
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 顶部工具栏：上传 | 模式 | 撤销 | 清空 | 下载 │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ K 线截图 + 标注画布区域 │
|
||||
│ │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ 底部图例：入场 / 出场 / 止损 颜色说明 │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 操作步骤
|
||||
|
||||
### 1. 上传 K 线截图
|
||||
|
||||
两种方式任选：
|
||||
|
||||
- 点击顶部 **「上传图片」**，选择本地 JPG / PNG 文件
|
||||
- 将图片 **拖拽** 到中间虚线框区域
|
||||
|
||||
上传后图片会按比例适应显示区域，**不会拉伸变形**。
|
||||
|
||||
> **注意**：上传新图片会自动 **清空上一轮所有标注线条**。
|
||||
|
||||
### 2. 选择标注模式
|
||||
|
||||
顶部三个模式按钮：
|
||||
|
||||
| 按钮 | 线条颜色 | 用途示例 |
|
||||
|------|----------|----------|
|
||||
| 入场线 | 绿色 `#00ff00` | 标记买入/开仓价位 |
|
||||
| 出场线 | 蓝色 `#0099ff` | 标记卖出/平仓价位 |
|
||||
| 止损线 | 红色 `#ff3333` | 标记止损价位 |
|
||||
|
||||
当前选中的模式会高亮显示。
|
||||
|
||||
### 3. 绘制水平线
|
||||
|
||||
1. 先选中一种标注模式（如「入场线」）
|
||||
2. 在 K 线图对应价位处 **单击鼠标左键**
|
||||
3. 系统会在该高度绘制一条 **贯穿整张图的水平线**（线宽 3px）
|
||||
|
||||
可重复切换模式并单击，添加多条不同颜色的线。
|
||||
|
||||
### 4. 拖拽调整线条
|
||||
|
||||
- 将鼠标移到已有线条附近，光标变为 **上下箭头**（`ns-resize`），表示可拖拽
|
||||
- **按住左键** 上下拖动，即可调整该线价位
|
||||
- 松开鼠标完成调整
|
||||
|
||||
### 5. 撤销与清空
|
||||
|
||||
| 按钮 | 作用 |
|
||||
|------|------|
|
||||
| 撤销 | 删除 **最后绘制** 的一条线 |
|
||||
| 清空全部 | 删除当前图片上的 **所有** 标注线（需确认） |
|
||||
|
||||
无线条时这两个按钮为灰色不可用。
|
||||
|
||||
### 6. 下载标注图
|
||||
|
||||
点击 **「下载标注图」**，浏览器会将 **原始分辨率图片 + 所有标注线** 合并为一张 PNG 并保存到本地。
|
||||
|
||||
文件名示例：`kline-label-20260527-143052.png`
|
||||
|
||||
> 导出使用原图像素尺寸，保证清晰度；线条位置会按显示比例自动换算到原图坐标。
|
||||
|
||||
## 隐私说明
|
||||
|
||||
- 所有图片与标注均在 **本机浏览器** 内处理
|
||||
- **不会上传到互联网或服务器**（服务器仅提供页面静态文件）
|
||||
- 关闭或刷新页面后，未导出的标注将丢失，请及时下载保存
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q：为什么单击没有画线？**
|
||||
A：请先上传图片，并确认已选中一种标注模式（入场/出场/止损）。
|
||||
|
||||
**Q：画线位置不准？**
|
||||
A：请确保在图片区域内单击；导出时会按原图比例校正坐标。
|
||||
|
||||
**Q：拖拽时误加了新线？**
|
||||
A：从线条上按下并拖动即可；仅在空白处单击才会新增线条。
|
||||
|
||||
**Q：支持哪些图片格式？**
|
||||
A：JPG、JPEG、PNG。
|
||||
|
||||
**Q：换了一张图，之前的线还在吗？**
|
||||
A：上传新图会自动清空所有旧标注。
|
||||
|
||||
## 快捷键
|
||||
|
||||
当前版本未定义键盘快捷键，全部通过鼠标与顶部按钮操作。
|
||||
Reference in New Issue
Block a user