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 配置和所有权，包含秘密，应私有保存。

换 VPS 在本地执行一条命令：

uvx --from 'flova==0.3.0' flova migrate rn root@新服务器IP --execute

新机使用干净的 Ubuntu 24.04 x86_64，并能从本地以 root SSH 登录。命令自动装依赖、停旧机打包、校验传输、恢复 uv/镜像/卷、合并 SSH/Git、更新 n8n SSH 地址并恢复原发布版本。不带 --execute 只预检；旧机保持停止，最后手动切 DNS。完整行为与回退边界见 迁移手册。

开发：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 不进入项目分发包。

远程盘点、清单备份恢复和 Docker 克隆见 主机管理，统一入口 flova host，无需本机服务器配置。原 Deploior 功能已全部迁入，配置模板为 examples/hosts.toml。

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