Skip to content

Commit dabb379

Browse files
ZhuLinsenZhuLinsen
committed
refactor(issue-1267): 能不能出个专为小白手把手教的视频部署教程
1 parent d0bb619 commit dabb379

4 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎docs/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
1616
- [修复] Pytdx 股票名称查询在全部服务器不可达时会短暂冷却，并在冷却期内跳过重复探测，减少无效拨号与告警噪音。
1717
- [修复] 调度模式未显式设置 `SCHEDULE_RUN_IMMEDIATELY` 时，会继续继承 `RUN_IMMEDIATELY` 的运行时覆盖语义，避免被持久化 `.env` 别名反向覆盖。
1818
- [文档] 补充 Longbridge 冷却开关与调度启动兼容语义说明。
19+
- [文档] 新增“面向新手的部署手把手视频教程”脚本文档，并补充文档中心/部署指南入口。
1920
- [新功能] Windows 桌面安装版接入 electron-updater，发现新版本后可后台下载并在用户确认后重启安装；Release 工作流同步上传自动更新所需元数据。
2021
- [测试] 完善桌面端更新链路验收说明：补充 `apps/dsa-desktop` 与打包产物元数据的本地验证步骤（Web 构建、桌面测试/构建、`latest.yml` 与 `*.blockmap` 检查），并明确 Windows/NSIS 部分需在 Windows 发布链路复核。
2122
- [测试] 补充 `docs/desktop-package.md` 对 Windows NSIS 与 `desktop-release` 链路的发布级复核要求：注明 Linux 环境不能直接产出 Windows 安装器，要求在 Windows 环境补齐 `latest.yml`/`*.blockmap` 与 installer 的版本一致性与附件核对。

‎docs/DEPLOY.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22

33
本文档介绍如何将 A股自选股智能分析系统部署到服务器。
44

5+
## 🎬 小白推荐路线：手把手视频脚本
6+
7+
如果你是第一次部署，建议优先按本视频教程先完成：
8+
[【小白手把手部署脚本】](deploy-beginner-video-script.md)
9+
文档内容覆盖：环境准备、`docker-compose` 一键启动、`web` 验证、常见错误排查。
10+
511
## 📋 部署方案对比
612

713
| 方案 | 优点 | 缺点 | 推荐场景 |

‎docs/INDEX.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
| --- | --- | --- |
99
| 快速了解项目能做什么 | [README](../README.md) | [完整配置与部署指南](full-guide.md) |
1010
| 第一次把项目跑起来 | [README](../README.md) | [完整配置与部署指南](full-guide.md) |
11+
| 第一次部署（小白友好） | [部署指南](DEPLOY.md) | [小白手把手部署视频脚本](deploy-beginner-video-script.md) |
1112
| 配置大模型渠道 | [LLM 配置指南](LLM_CONFIG_GUIDE.md) | [LLM 服务商配置指南](llm-providers.md) |
1213
| 配置推送通知 | [通知能力基线](notifications.md) | [完整配置与部署指南](full-guide.md) |
1314
| 部署到服务器或云平台 | [部署指南](DEPLOY.md) | [云端 WebUI 部署](deploy-webui-cloud.md)、[Zeabur 部署](docker/zeabur-deployment.md) |
@@ -48,6 +49,7 @@
4849
| 文档 | 内容 |
4950
| --- | --- |
5051
| [部署指南](DEPLOY.md) | 服务器部署、Docker、systemd、Supervisor 等部署方式 |
52+
| [小白手把手部署视频脚本](deploy-beginner-video-script.md) | 从零到会跑的录屏版流程，含环境准备、启动验证和排障 |
5153
| [云端 WebUI 部署](deploy-webui-cloud.md) | 云服务器访问 WebUI 的部署说明 |
5254
| [Zeabur 部署](docker/zeabur-deployment.md) | Zeabur 平台部署说明 |
5355
| [桌面端打包说明](desktop-package.md) | Electron 桌面端和 Web 构建产物打包说明 |

‎docs/deploy-beginner-video-script.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# 小白手把手部署视频教程（适配第一次部署）
2+
3+
> 建议时长：12–18 分钟
4+
> 目标：`新手 0 背景` 也能在 1 台 Linux 云服务器上跑通本项目
5+
6+
本文档用于“照着录一套可直接发视频的讲解脚本 + 实操清单”。
7+
默认路线：**本地测试 → 云服务器 Docker Compose 正式上线**。
8+
可选路线：最后给出直接运行方式，便于本地或开发机快速验证。
9+
10+
---
11+
12+
## 适用范围（先说清楚）
13+
14+
1. 你有一台 Ubuntu/CentOS 服务器（推荐 Ubuntu 20.04/22.04）
15+
2. 你有项目运行所需的 Key（至少一项 AI Key）
16+
3. 你希望先“看视频一条龙学会”，后续自己能自行复测
17+
18+
## 录制脚本（按时间轴）
19+
20+
### 0:00 - 0:30 开场（先交代目标）
21+
22+
**画面**：打开本项目主页截图 + 本文档标题。
23+
**口播**：
24+
“今天我们用新手友好方式把 `daily_stock_analysis` 从 0 到可运行做一遍：先把环境准备好，复制 `.env`，启动服务，最后验证 Web 界面和一次手工分析。即使你没接触过 Python 或 Docker 也能照着做。”
25+
26+
### 0:30 - 2:00 讲清准备工作
27+
28+
**画面**：终端，展示服务器信息和软件版本。
29+
30+
1. 说明将用的部署方式（Docker Compose 推荐）
31+
2. 说明最少权限：有 SSH 登录、可执行 `sudo`
32+
33+
建议在讲解时同步贴出这张命令清单：
34+
35+
```bash
36+
uname -a
37+
python3 --version || true
38+
git --version
39+
docker --version || true
40+
docker-compose --version || true
41+
```
42+
43+
### 2:00 - 4:30 安装前置环境（首次）
44+
45+
**口播**：
46+
“没有 Docker 就先安装，不用一次次折腾。”
47+
48+
#### Ubuntu/Debian
49+
50+
```bash
51+
curl -fsSL https://get.docker.com | sh
52+
sudo usermod -aG docker "$USER"
53+
newgrp docker
54+
```
55+
56+
#### CentOS
57+
58+
```bash
59+
sudo yum install -y docker docker-compose
60+
sudo systemctl start docker
61+
sudo systemctl enable docker
62+
```
63+
64+
**小提示**：这一步若提示 `docker-compose` 命令不存在，先确认系统有 `docker-compose`；若只有 `docker compose`，则统一改成后续命令即可（本教程先按 `docker-compose` 命令执行）。
65+
66+
### 4:30 - 6:30 获取代码并准备配置文件
67+
68+
**画面**：`ls`、`git clone`、目录切换
69+
70+
```bash
71+
cd /opt
72+
git clone <your-repo-url> stock-analyzer
73+
cd stock-analyzer
74+
cp .env.example .env
75+
```
76+
77+
然后重点讲 `.env` 的“最小可运行配置”：
78+
79+
1. `STOCK_LIST`（必须）
80+
2. 至少一个模型 Key：`ANSPIRE_API_KEYS` 或 `AIHUBMIX_KEY` 或 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`
81+
3. 通知渠道至少一个：如 `WECHAT_WEBHOOK_URL` 或 `EMAIL_SENDER` + `EMAIL_PASSWORD`
82+
4. 搜索增强至少一个：`ANSPIRE_API_KEYS` 或 `SERPAPI_API_KEYS`（推荐）
83+
84+
命令示例（按需修改）：
85+
86+
```bash
87+
vim .env
88+
```
89+
90+
**口播**：
91+
“先别怕，少填也能先把框架跑通；后续再回来补齐高级参数。”
92+
93+
### 6:30 - 9:00 一键启动（Docker 推荐）
94+
95+
```bash
96+
docker-compose -f ./docker/docker-compose.yml up -d
97+
```
98+
99+
启动后给 3 秒等待，再看三条验证命令：
100+
101+
```bash
102+
docker-compose -f ./docker/docker-compose.yml ps
103+
docker-compose -f ./docker/docker-compose.yml logs -f --tail=80
104+
docker-compose -f ./docker/docker-compose.yml exec -u dsa stock-analyzer python main.py --help
105+
```
106+
107+
#### 预期结果
108+
- 容器状态 `Up`
109+
- 日志出现服务初始化信息（无立即报错退出）
110+
- `--help` 能输出命令列表
111+
112+
### 9:00 - 10:30 验证 Web 访问
113+
114+
**画面**：浏览器输入 `http://服务器IP:8000`
115+
116+
```bash
117+
sudo ufw allow 8000/tcp # 若你在用 UFW
118+
```
119+
120+
**说明**：有些场景是云厂商安全组也要放行 8000 端口。
121+
提示：可先从“本地测试”到“外网访问”过度，避免一上来就盲目排查网络。
122+
123+
### 10:30 - 12:00 手工触发一次分析任务（最关键）
124+
125+
**方式 A：容器内执行一次**
126+
127+
```bash
128+
docker-compose -f ./docker/docker-compose.yml exec -u dsa stock-analyzer python main.py --no-notify
129+
```
130+
131+
**方式 B：用 Web 界面**
132+
打开 WebUI，点击分析按钮并观察状态变化与报告页。
133+
134+
**验收点**：
135+
- 任务能从“进行中”变为“完成”
136+
- 关键指标输出有返回（不是卡死或 500）
137+
- 成功时可见报告结果 / 日志中无致命异常
138+
139+
### 12:00 - 13:30 加入定时任务（可选）
140+
141+
**口播**：
142+
“如果你只是想先跑一遍，先别急着加定时；先确认单次能跑，再加 schedule。”
143+
144+
建议配置：
145+
- `SCHEDULE_ENABLED=true`（或运行时使用 `--schedule`）
146+
- `SCHEDULE_TIME=18:00`（默认可直接沿用）
147+
- 时区使用 `Asia/Shanghai`
148+
149+
### 13:30 - 15:00 追加：本地/开发机直接部署（备选）
150+
151+
**当你不想用 Docker，或者只想临时验证时可用。**
152+
153+
```bash
154+
python3.10 -m venv venv
155+
source venv/bin/activate
156+
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
157+
cp .env.example .env
158+
vim .env
159+
python main.py
160+
```
161+
162+
### 15:00 - 17:00 常见错误快速排查（视频结尾金句）
163+
164+
#### 症状 1：页面可以打开但资源乱掉
165+
166+
```bash
167+
tail -n 120 /opt/stock-analyzer/logs/stock_analysis_*.log
168+
```
169+
说明 `static/assets` 资源是否 404；若有，按 `DEPLOY.md` 中“资源重建”步骤重做镜像。
170+
171+
#### 症状 2：容器一直重启 / 退出 1
172+
173+
```bash
174+
docker-compose -f ./docker/docker-compose.yml logs -f --tail=120
175+
```
176+
重点看 `.env` 是否缺项、AI Key 是否错误、数据库路径是否可写。
177+
178+
#### 症状 3：端口访问失败
179+
180+
```bash
181+
docker-compose -f ./docker/docker-compose.yml exec stock-analyzer ss -lntp | grep 8000
182+
sudo ufw status
183+
```
184+
常见是 8000 没放行或进程未监听。
185+
186+
#### 症状 4：命令返回 `Permission denied`
187+
188+
- 检查容器执行用户与挂载目录权限
189+
- 该项目文档默认 `data/logs/reports` 由入口处理权限修正；若仍异常，可先检查挂载点属主。
190+
191+
### 17:00 - 18:00 一句话收口
192+
193+
**口播**：
194+
“你现在已经能完成从 `克隆项目`、`配置 .env`、`Docker 一键启动`、`手动跑一次分析` 的完整流程。后续只要保持 `.env` 秘钥和 `STOCK_LIST` 有效，日常就是看日志和任务结果。下一篇可以做‘通知渠道细节配置’专项。”
195+
196+
---
197+
198+
## 适合放到录屏里的台词清单（可直接复制）
199+
200+
- “先把环境装好，再装业务；先有结果，再追求漂亮。”
201+
- “这个项目支持 Docker 和直接运行，先用 Docker 是为了快、稳、少踩坑。”
202+
- “今天只追求‘一次能跑’，不是‘一次配置完美’。”
203+
- “遇到问题别看日志都不懂先按 checklist：进程、端口、配置、权限、日志。”
204+
205+
## 录制素材建议（可选）
206+
207+
- `terminal` 全程同屏（建议字体放大）
208+
- 命令输入前后用 `sleep` 暂停 2-3 秒，方便新手跟读
209+
- 出错演示建议加一个“故意错配端口”片段再回到正确流程，记忆度更高
210+
211+
---
212+
213+
## 交付核对清单
214+
215+
- [ ] 服务器可 SSH
216+
- [ ] Docker / docker-compose 可用
217+
- [ ] `.env` 至少填了 `STOCK_LIST` + 一个模型 Key
218+
- [ ] `docker-compose up -d` 后服务状态为 `Up`
219+
- [ ] 可访问 `http://IP:8000`
220+
- [ ] `python main.py --no-notify` 在容器内能单次执行通过
221+
- [ ] 至少出现一次成功报告/日志完成记录
222+

0 commit comments

Comments
 (0)