zikai
9af28f41b4
死代码移除: - whiteboard_hub.py: 移除未引用的 reset_hub 单例重置函数 - tunnel_service.py: 移除未引用的 is_port_allowed (逻辑已在 sftp_server 内联) - tunnel_session_dao.py: 移除未引用的 get_active_by_port - pdf_job_dao.py: 移除未用 datetime 导入 - pdf_converter.py: 移除未用 shutil 导入 - pdf_service.py: 移除未用 PdfSubmitResponse 导入 + _do_convert 内未用 hashlib 导入 - upload_html.py: 移除未用 escape 导入 (JS 侧自有 escapeHtml) - pdf_controller.py: 移除 _resolve_cookie 内未用 cfg 局部变量 提前失败/分层修复: - database.py init_db_schema: 建表后用 inspector 校验既有表列与模型一致, 缺列即抛 RuntimeError (fail-fast on schema drift), 避免运行期才暴露 - whiteboard_dao.get_or_create: 仅 IntegrityError 才回滚重读, 其他异常向上抛 (原 except Exception 会掩盖 schema/连接等真实故障) - pdf_service.admin_delete/_safe_delete_file: 改用 PdfJobDAO.delete / UploadedFileDAO.delete, 不再直接操作 job_dao.db / file_dao.db (修复分层契约: DAO 头注释声明 service 不直接操作 session) - PdfJobDAO 新增 delete(job) 方法 日志补全 (8 处 silent catch): - whiteboard_hub.py disconnect/close_board 关闭 ws: logger.debug - whiteboard_controller _safe_send/_safe_close: logger.debug - sftp_server _close_tunnel_dao/读用户名: logger.debug - sftp_server validate_public_key: logger.warning (auth 路径, 避免静默失败) 文档: - 新增 docs/routes.md, docs/configuration.md, docs/error-handling.md - README.md 精简为简介/结构/外部依赖/apache2 配置/Ubuntu 安装/docs 链接
5.3 KiB
5.3 KiB
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部署前端。