个人资料库 (Personal Resource Library)

基于 Flask + MySQL 的个人多媒体资料管理系统。支持文本、图片、音频、视频的上传、URL 下载、磁力下载及在线预览。

Demo 地址： https://prl.hty1024.com

功能特性

功能	说明
权限管理	管理员 / 普通用户两级权限，登录保护所有页面
资源管理	文本、图片、音频、视频四类资源
本地上传	拖拽或点击上传，带实时进度条
URL 下载	后台异步下载远程文件，实时轮询进度
磁力下载	调用 aria2c 在后台下载磁力链接资源
在线预览	文本高亮 / 图片查看 / HTML5 音视频播放器
安全	bcrypt 加盐哈希密码、CSRF 防护、SQL 注入防护、XSS 防护

快速开始

1. 本地开发

环境要求： Python 3.10+、MySQL 8.0+、（可选）aria2c

# 安装依赖
pip install -r requirements.txt

# 配置环境
cp .env.example .env
# 编辑 .env，设置 DATABASE_URL 和 SECRET_KEY

# 初始化数据库
python init_db.py
# 自定义管理员：python init_db.py --admin-user admin --admin-pass YourPass123

# 启动
python run.py

访问 http://localhost:5000，默认管理员：用户名 admin，密码 Admin@123456

---

2. Docker 部署（一键脚本）

适用于 Ubuntu / Debian / CentOS / RHEL / Alpine / Arch 等主流 Linux 发行版

git clone <仓库地址>
cd ai-app-database
bash scripts/deploy.sh

脚本会引导完成所有配置，支持两种部署模式：

模式	说明
新建 MySQL（默认）	用 Docker 启动 MySQL，适合全新服务器
使用已有 MySQL	连接外部数据库，适合已有数据库的场景

更新服务：

bash scripts/update.sh
# 支持参数：--yes（跳过确认）、--tag <镜像标签>

---

3. 手动 Docker Compose 部署

方式 A：新建 MySQL（完整栈）

cp .env.docker.example .env.docker
# 编辑 .env.docker，设置密码和 SECRET_KEY
docker compose --env-file .env.docker up -d
# 含 Nginx：docker compose --env-file .env.docker --profile nginx up -d

方式 B：外置 MySQL

cp .env.external-db.example .env.external-db
# 编辑 .env.external-db，填写 DATABASE_URL 等
docker compose -f docker-compose.external-db.yml --env-file .env.external-db up -d

---

CI/CD 自动化

Gitea Actions 工作流

工作流	触发条件	说明
ci.yml	push 到 main / master / develop	构建镜像并推送至 Gitea 镜像仓库
release.yml	push v* tag（如 v1.2.3）	构建正式版镜像，生成多级标签
deploy-demo.yml	CI 完成后自动触发 / 手动触发	部署到 Demo 环境（self-hosted runner）

镜像标签规则

触发	生成标签
push main	:latest、:sha-<短commit>
push develop	:develop、:sha-<短commit>
push v1.2.3	:1.2.3、:1.2、:1、:latest
push v1.2.3-rc1	:1.2.3-rc1（不推送 :latest）

配置 Secrets

在 Gitea → 仓库 → 设置 → Secrets 中添加：

Secret 名称	用途	备注
REGISTRY_TOKEN	推送 / 拉取镜像	需要 package:write 权限
DEMO_SECRET_KEY	Flask SECRET_KEY	随机字符串，≥32 位
DEMO_ADMIN_PASS	Demo 管理员密码	首次部署后可修改

注意： Gitea 禁止以 GITEA_ 或 GITHUB_ 开头的 Secret 名称。

---

Demo 环境

项目	配置
访问地址	https://prl.hty1024.com
部署方式	Docker + 外置 MySQL + Caddy 反向代理
运行位置	Gitea runner 同一服务器（self-hosted）
自动更新	push 到 main 分支后，CI 成功即自动部署

Caddy 配置

Demo 环境使用外置 Caddy 提供反向代理和自动 TLS。

1. 在主 Caddyfile 中启用 sites 目录导入：

# /etc/caddy/Caddyfile
{
    email your@email.com
}

import /etc/caddy/sites/*.caddy

2. 复制站点配置：

sudo mkdir -p /etc/caddy/sites
sudo cp docker/caddy/prl.hty1024.com.caddy /etc/caddy/sites/
sudo systemctl reload caddy

Caddy 会自动申请并续期 Let's Encrypt TLS 证书。

---

项目结构

.
├── app/
│   ├── models/          # 数据库模型 (User, Resource, SystemSetting)
│   ├── routes/          # 路由蓝图 (auth, admin, resources, main, errors)
│   ├── utils/           # 工具模块 (decorators, file_handler, downloader)
│   ├── static/          # 静态文件 (CSS, JS)
│   │   └── uploads/     # 用户上传文件目录（自动创建）
│   └── templates/       # Jinja2 模板
├── docker/
│   ├── entrypoint.sh    # 容器入口脚本（等待DB、初始化、启动）
│   ├── nginx.conf       # Nginx 反向代理配置（可选）
│   └── caddy/
│       └── prl.hty1024.com.caddy  # Demo 环境 Caddy 站点配置
├── scripts/
│   ├── deploy.sh        # Linux 一键部署脚本
│   └── update.sh        # 一键更新脚本（含自动回滚）
├── .gitea/workflows/
│   ├── ci.yml           # CI：构建并推送镜像
│   ├── release.yml      # Release：正式版镜像
│   └── deploy-demo.yml  # Demo 环境自动部署
├── docker-compose.yml             # 完整栈（含 MySQL）
├── docker-compose.external-db.yml # 外置数据库模式
├── .env.docker.example            # 完整栈环境变量模板
├── .env.external-db.example       # 外置 DB 环境变量模板
├── Dockerfile
├── config.py
├── init_db.py           # 数据库初始化脚本
├── run.py               # 本地开发启动入口
└── requirements.txt

安全设计

安全措施	实现方式
密码存储	Flask-Bcrypt（bcrypt 自动加盐哈希）
CSRF 防护	Flask-WTF CSRFProtect，所有 POST 请求验证 token
权限控制	Flask-Login @login_required + 自定义 @admin_required
SQL 注入	SQLAlchemy ORM 参数化查询
XSS 防护	Jinja2 自动转义 HTML 输出
文件安全	werkzeug.secure_filename + 扩展名白名单验证
Session	HTTPOnly Cookie + SameSite=Lax

磁力下载说明

磁力下载需要在服务器上安装 aria2c：

• Linux：apt install aria2 / yum install aria2
• macOS：brew install aria2
• Windows：从 aria2 Releases 下载并加入 PATH