zTools2 - 个人 Web 服务后端

基于 FastAPI 的个人 Web 服务后端，提供文件上传/浏览/下载、共享记事本（实时协作）、主机监控、SFTP 暂存、反向隧道、PDF 转换。采用 Spring 风格分层架构（controller -> service -> dao -> ORM model -> MySQL），自带 API 文档。

所有入口统一挂在 /api/ 前缀下，前端用同源相对路径调用，无需区分 dev/prod。前端子项目（timeTableFix、zPDF_package、zWhiteBoard）经 zMainPage 构建期组件 import 集成，生产由 apache2 静态托管 + /api 反代到本服务。

项目结构

zTools2/
├── app/
│   ├── main.py              # FastAPI 应用工厂、路由注册、生命周期（reaper）
│   ├── config.py            # 从 config.yaml 加载的类型化 Settings（pydantic-settings）
│   ├── database.py          # SQLAlchemy 引擎/Session/Base/get_db 依赖 + schema 校验
│   ├── security.py          # Basic Auth（require_docs_auth，常量时间比较）
│   ├── controllers/         # 路由层：file/system/chunk/tunnel/whiteboard/pdf/admin
│   ├── services/            # 业务层：Upload/ChunkUpload/System/Whiteboard/Tunnel/Pdf/sftp
│   ├── dao/                 # 数据访问层：唯一发 SQL 的层（SQLAlchemy ORM 参数化）
│   ├── models/              # ORM 实体：UploadedFile/UploadSession/Whiteboard/TunnelSession/PdfJob
│   ├── schemas/             # pydantic 请求/响应 DTO
│   ├── views/               # 服务端渲染 HTML（系统状态页、上传页）
│   ├── static/              # 前端静态资源
│   └── scripts/init_db.py   # 数据库初始化（建库建账、随机密码写回 config.yaml）
├── sql/schema.sql           # 建表 DDL（参考；实际由 ORM 自动建表）
├── config.example.yaml      # 配置模板（含注释）
├── config.yaml              # 实际配置（git-ignored，含密码）
├── requirements.txt
├── setup.sh                 # 一次性初始化：venv + 依赖 + 建库 + SFTP 密钥
├── start.sh / stop.sh       # 启停 HTTP（127.0.0.1:6867）+ SFTP（2022）
└── deploy/                  # systemd 持久化部署

请求流程：controller -> service -> dao -> ORM model -> MySQL。DB Session 由 get_db 依赖注入。

外部依赖

项	说明
Python	≥ 3.11（用 .venv）
MySQL	8.x（独立库 zikai_filesvc，由 setup.sh 建账）
Apache2	反向代理对外提供 HTTPS；服务本身只绑 127.0.0.1:6867
系统库	libpango/cairo（weasyprint PDF 转换）、build-essential（bcrypt/asyncssh 编译）

Apache2 反向代理配置

服务只绑 127.0.0.1:6867，通过 Apache 对外提供 HTTPS。安装模块并配置 vhost：

a2enmod ssl proxy proxy_http proxy_wstunnel rewrite headers

创建 /etc/apache2/sites-available/f.zikai.wang.conf（关键部分）：

<VirtualHost *:443>
    ServerName f.zikai.wang
    SSLEngine on
    SSLCertificateFile     /etc/letsencrypt/live/f.zikai.wang/fullchain.pem
    SSLCertificateKeyFile  /etc/letsencrypt/live/f.zikai.wang/privkey.pem

    ProxyPreserveHost On
    ProxyPass        /fdata !
    # 所有 zTools2 入口（页面/静态/探针/WS/API）统一在 /api/ 下，一条规则即可；
    # WebSocket 走 /api/ws/wb/{id}，靠 proxy_wstunnel 透传 Upgrade 头
    ProxyPass        /api/ http://127.0.0.1:6867/api/
    ProxyPassReverse /api/ http://127.0.0.1:6867/api/
    ProxyTimeout 300
</VirtualHost>

a2ensite f.zikai.wang
systemctl reload apache2

防火墙：放开 443（HTTPS）与 2022（SFTP）。6867 不对外（仅 loopback）。 大文件上传：Apache 全局 Timeout 300，慢链路建议走分片上传（/api/upload）或 SFTP。

从零安装（Ubuntu 22.04+）

1. 安装系统依赖

apt update
apt install -y python3-venv python3-pip mysql-server apache2 \
    libssl-dev build-essential  # build-essential 给 bcrypt/asyncssh 编译
# PDF 转换依赖 weasyprint，需 pango/cairo 系统库：
apt install -y libpango-1.0-0 libpangoft2-1.0-0 libcairo2 libgdk-pixbuf-2.0-0

2. 获取代码并初始化

git clone <repo> /root/zikai
cd /root/zikai/zTools2
./setup.sh    # 创建 .venv + 装依赖 + 复制 config.yaml + 建 MySQL 库账 + 生成 SFTP 密钥

3. 配置凭据

编辑 config.yaml（详见 docs/configuration.md）：docs.username/password（管理页 Basic Auth）、sftp.users[].password_hash（bcrypt）、可选 tunnel.users[]。

4. 启动

./start.sh    # 启动 HTTP(127.0.0.1:6867) + SFTP(0.0.0.0:2022)
./stop.sh     # 停止

5. 持久化部署（systemd）

./deploy/install-systemd.sh     # 安装并启动 ztools2 服务（开机自启）
systemctl status ztools2
journalctl -u ztools2 -f

与 zMainPage 整体部署配合：systemd 管后端，zMainPage/deploy.sh --no-restart 部署前端。

了解更多

• 路由与访问入口
• 配置说明
• 错误处理与日志约定