Flova

Flova 把个人自动化的 webhook、只读账本查询、财务适配和服务器启停合成一个可安装的项目。配置与业务数据留在服务器，源码留在本地。

uv tool install 'flova[download]'
flova --config /path/to/flova.toml config check
flova webhook serve
flova finance prepare --offline --date 2026-10-03
flova finance finish --write --decisions-base64 'BASE64_JSON'
flova service start
flova service restore  # 仅恢复资源，不启动任务
flova service stop
flova service check
flova service pack
flova service pack --keep-stopped  # 正式迁移，成功后保持旧机停止

仅运行 ledger 时安装 uv tool install 'flova[ledger]'，用 flova ledger serve 启动，或 flova ledger query --start YYYY-MM-DD --end YYYY-MM-DD 查询。

flova download -p alipay --download-config /path/to/download.json 使用现有下载库的提供者工厂，并明确读取配置路径，不再改写第三方包源码。

flova-download download 提供旧 dflow 命令的参数和 JSON 兼容入口，服务器 dflow 入口指向它。

默认配置 /root/.flow/config/flova.toml。支持 ${ENV_NAME} 占位符，缺失变量直接报错。模板见 examples/。--config 和 --root 是全局参数，放在功能指令前。FLOVA_CONFIG、FLOVA_ROOT 可设置默认位置。

Webhook 验证 GitHub HMAC SHA256，只响应指定分支的 push；同一仓库同步互斥，保持旧服务的 fetch/reset/clean 镜像同步语义。因此应指向自动部署仓库，不应指向有未提交人工改动的开发目录。同步后的可选 HTTP hook 由配置指定；失败记录类型，不把凭据或请求正文写入日志。

账本接口保持 GET /health 和 POST /query，字段 start_date、end_date、max_transactions，仍输出 schema_version=1、收入/支出/资产负债变动、分录及警告。日期范围最多366天；查询只读。

财务功能只编排 fa、下载提供者和 oub；Fane 负责解析、模板、去重和分类。prepare --offline 不下载、解压、写交易、调用AI或推送。finish 不带 --write 为预览；未配置实际订阅计划时明确失败，不假装成功。

服务指令读取服务器 config/services.json 和唯一 config/compose.yaml。启动重复执行不会重建正在运行的容器。普通打包短暂停止 webhook、暂停容器以复制一致数据，立即恢复，再导出镜像。正式迁移使用 --keep-stopped：先停稳服务再复制数据，成功后旧机保持停止，禁用 webhook 自启与容器自动重启；失败或回退启动恢复原策略。包保留 n8n 配置和所有权，包含秘密，应私有保存。

新服务器使用相同 Python 3.12 和 x86_64，事先安装 Docker/Compose、Git 和 msmtp。uv 随包迁移。解包至 /root 后先执行 /root/.flow/start.sh restore，按 迁移手册 暂停新机 n8n 发布，再启动检查及切换。SSH 私钥、域名 DNS 及 n8n SSH 服务器地址需单独迁移。

开发：uv sync --all-extras，uv run python -m unittest discover -s tests，uv run ruff check src tests。发布：PYPI_TOKEN_FILE=/private/path/token ./release.sh --yes。token 不进入项目分发包。

完整换 VPS 步骤见 迁移手册，部署概览见 服务器说明，完整参数见 指令参考，财务流程见 n8n说明。发布新版本前先提高 pyproject.toml 版本号，PyPI 已发布版本不能覆盖。