GuangYu/UploaderHui
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Nelson
2026-04-18 15:08:57 +08:00
commit 2a67f56512
13 changed files with 2729 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

389
部署文档.md Normal file
View File

@@ -0,0 +1,389 @@
# NAS图片上传系统 - 部署文档
> **适用环境**：群晖NAS + 公网服务器（frp内网穿透）
> **最后更新**：2026-04-17
---
## 1. 部署前准备
### 1.1 你需要的东西
| 项目 | 说明 |
|------|------|
| 群晖NAS | 已开启SSH，能通过终端访问 |
| 公网服务器 | 有公网IP，已安装frps（frp服务端） |
| NAS存储路径 | 决定图片存放在哪个共享文件夹下 |
### 1.2 项目文件清单
部署前确认以下文件完整：
```
nas-uploader/
├── app.py ← Flask后端主程序
├── config.py ← 配置读取模块
├── .env.example ← 配置模板（需复制为.env）
├── requirements.txt ← Python依赖
├── start.sh ← 启动脚本
├── static/
│ ├── css/style.css ← 页面样式
│ ├── js/app.js ← 前端逻辑
│ └── img/ ← 图标资源（可选）
└── templates/
└── index.html ← 主页面
```
---
## 2. 群晖NAS上的部署步骤
### 2.1 上传项目文件
**方法一：通过群晖网页上传**
1. 打开群晖 File Station
2. 进入你想存放项目的共享文件夹（如 `web`）
3. 上传整个 `nas-uploader` 文件夹
**方法二：通过SSH上传**
```bash
# 在你的电脑上执行（假设NAS内网IP为 192.168.1.100）
scp -r nas-uploader/ your_admin@192.168.1.100:/volume1/web/
```
### 2.2 SSH登录群晖NAS
```bash
ssh your_admin@192.168.1.100
```
> 如果提示"connection refused"，需要在群晖控制面板 → 终端机和SNMP → 开启SSH功能
### 2.3 配置环境
```bash
# 进入项目目录（根据你的实际路径调整）
cd /volume1/web/nas-uploader
# 复制配置文件
cp .env.example .env
# 编辑配置文件
vi .env
```
**必须修改的配置项：**
```env
# 改成你实际的NAS存储路径，例如：
NAS_DATA_PATH=/volume1/photo/训练营图片
# 其他配置一般不需要改
PORT=5000
ALLOWED_EXTENSIONS=jpg,jpeg,png,gif,webp
MAX_FILES_COUNT=100
MAX_FILE_SIZE_MB=20
```
> 💡 **路径说明**：`NAS_DATA_PATH` 是图片存储的根目录，上传的图片会保存在这个目录下的 `训练营N期/X班/` 子文件夹中。建议使用群晖已有的共享文件夹路径。
### 2.4 安装Python依赖
群晖NAS自带Python 3，但可能缺少pip。按以下步骤操作：
```bash
# 检查Python版本
python3 --version
# 如果有pip，直接安装
pip3 install flask python-dotenv
# 如果提示权限问题
pip3 install flask python-dotenv --break-system-packages
# 如果没有pip，先安装
# 群晖DS718+等型号可以直接通过套件中心安装Python3
```
### 2.5 首次启动测试
```bash
cd /volume1/web/nas-uploader
python3 app.py
```
看到以下输出说明启动成功：
```
服务启动在 http://0.0.0.0:5000
* Running on http://127.0.0.1:5000
```
此时在浏览器访问 `http://NAS内网IP:5000` 应该能看到上传页面。
### 2.6 验证上传功能
1. 打开 `http://NAS内网IP:5000`
2. 选择训练营和班级
3. 选择几张图片上传
4. 检查 `NAS_DATA_PATH` 目录下是否自动创建了对应的文件夹和图片文件
5. 检查统计.md是否正确生成
---
## 3. 配置frp内网穿透
> 详细原理请参考 [frp内网穿透_原理与部署指南.md](./frp内网穿透_原理与部署指南.md)
### 3.1 在NAS上配置frpc
如果NAS上还没有frpc，先安装：
```bash
# 下载frp（根据NAS架构选择）
# x86架构（大多数群晖）
wget https://github.com/fatedier/frp/releases/download/v0.61.1/frp_0.61.1_linux_amd64.tar.gz
tar -xzf frp_0.61.1_linux_amd64.tar.gz
cd frp_0.61.1_linux_amd64
```
创建配置文件 `frpc.toml`：
```toml
serverAddr = "你的公网服务器IP"
serverPort = 7000
auth.token = "你的frp认证密码"
[[proxies]]
name = "nas-uploader"
type = "tcp"
localIP = "127.0.0.1"
localPort = 5000
remotePort = 8080
```
启动frpc：
```bash
./frpc -c frpc.toml
```
### 3.2 公网服务器上的frps配置
确保公网服务器上的 `frps.toml` 已配置好：
```toml
bindPort = 7000
auth.token = "你的frp认证密码" # 和frpc保持一致
```
### 3.3 验证公网访问
在手机或电脑上（使用非内网网络）访问：
```
http://公网服务器IP:8080
```
如果能打开上传页面，说明穿透配置成功。
---
## 4. 设置开机自启（推荐）
### 4.1 Flask服务自启
在NAS上创建systemd服务：
```bash
sudo vi /etc/systemd/system/nas-uploader.service
```
写入以下内容（**注意修改路径**）：
```ini
[Unit]
Description=NAS Image Uploader
After=network.target
[Service]
Type=simple
WorkingDirectory=/volume1/web/nas-uploader
ExecStart=/usr/bin/python3 /volume1/web/nas-uploader/app.py
Restart=always
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
启用服务：
```bash
sudo systemctl enable nas-uploader
sudo systemctl start nas-uploader
# 查看状态
sudo systemctl status nas-uploader
```
> ⚠️ **注意**：部分群晖型号可能不支持systemd，可以用 `supervisor` 替代，或者通过群晖的"任务计划"功能设置开机脚本。
### 4.2 frpc自启
```bash
sudo vi /etc/systemd/system/frpc.service
```
```ini
[Unit]
Description=frp client
After=network.target
[Service]
Type=simple
ExecStart=/volume1/web/frp/frpc -c /volume1/web/frp/frpc.toml
Restart=always
RestartSec=5s
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl enable frpc
sudo systemctl start frpc
```
### 4.3 使用群晖任务计划（替代方案）
如果systemd不可用，可以通过群晖控制面板设置：
1. 控制面板 → 任务计划 → 新增 → 触发的任务 → 用户自定义脚本
2. 常规：设置任务名称"启动图片上传服务"
3. 事件：开机
4. 任务设置：用户账号选root，脚本内容：
```bash
#!/bin/bash
cd /volume1/web/nas-uploader
nohup python3 app.py > /volume1/web/nas-uploader/app.log 2>&1 &
cd /volume1/web/frp
nohup ./frpc -c frpc.toml > /volume1/web/frp/frpc.log 2>&1 &
```
---
## 5. 群晖Docker部署（可选）
如果你的群晖支持Docker（Container Manager套件），可以用Docker部署：
### 5.1 创建Dockerfile
在项目根目录创建 `Dockerfile`：
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python3", "app.py"]
```
### 5.2 构建和运行
```bash
cd /volume1/web/nas-uploader
# 构建镜像
docker build -t nas-uploader .
# 运行容器
docker run -d \
--name nas-uploader \
--restart always \
-p 5000:5000 \
-v /volume1/photo/训练营图片:/app/data \
-e NAS_DATA_PATH=/app/data \
nas-uploader
```
> `-v` 参数将NAS的存储目录挂载到容器内
---
## 6. 常见问题排查
### 6.1 页面打不开
```
检查步骤：
1. Flask服务是否在运行？
→ systemctl status nas-uploader 或 ps aux | grep python
2. 端口是否被占用？
→ netstat -tlnp | grep 5000
3. 防火墙是否放行？
→ 群晖控制面板 → 安全性 → 防火墙 → 编辑规则
```
### 6.2 公网打不开
```
检查步骤：
1. frpc是否在运行？ → ps aux | grep frpc
2. frpc日志有无报错？ → cat /path/to/frpc.log
3. 公网服务器防火墙是否开放了8080端口？
4. frp的token是否一致？
```
### 6.3 上传失败
```
检查步骤：
1. NAS_DATA_PATH路径是否正确？ → ls -la 路径
2. 目录是否有写入权限？ → touch 路径/test && rm 路径/test
3. 磁盘空间是否充足？ → df -h
4. 查看Flask日志 → cat /path/to/nas-uploader/app.log
```
### 6.4 图片上传后找不到文件
```
检查步骤：
1. 确认.env中的NAS_DATA_PATH路径
2. 查看该路径下是否生成了训练营文件夹
3. 文件夹名称格式必须是"训练营N期"
```
---
## 7. 维护命令速查
| 操作 | 命令 |
|------|------|
| 启动服务 | `cd /volume1/web/nas-uploader && python3 app.py` |
| 停止服务 | `sudo systemctl stop nas-uploader` |
| 重启服务 | `sudo systemctl restart nas-uploader` |
| 查看日志 | `sudo journalctl -u nas-uploader -f` |
| 查看存储目录 | `ls -la $NAS_DATA_PATH` |
| 查看磁盘空间 | `df -h` |
| 手动更新统计 | `python3 -c "from app import update_statistics; update_statistics('训练营13期')"` |
---
## 8. 安全建议
- **当前版本无密码保护**，任何人知道网址都可以上传
- 建议不要将网址公开分享给无关人员
- 后续版本会添加访问密码功能
- 建议定期检查上传的文件，防止滥用
- 如果发现异常，可以暂时停止Flask服务：`sudo systemctl stop nas-uploader`