开源 · Python · DevOps Open source · Python · DevOps

Keeploy 零停机部署 Keeploy — Zero-downtime Deploy

Nginx 无感滚动发布 · 密码纯本地 · Dockerless Nginx rolling deploy · Local credentials · Dockerless

把「上传 → 摘流 → 替换 → 健康检查 → 恢复」做成可重复、可回滚的流水线。 Turn "upload → drain → swap → health check → restore" into a repeatable, rollbackable pipeline.

★ Star on GitHub★ Star on GitHub 了解更多Learn More

Keeploy 是一个基于 KeePass 凭据托管的 Nginx 负载均衡无感滚动部署工具。它不依赖 Docker，也不要求目标机安装任何中间件——只靠 SSH 上传与 Nginx 配置操作，就把上线这件事变得可重复、可回滚、fail-fast。 Keeploy is a KeePass-backed, Nginx load-balancer zero-downtime rolling deployment tool. Dockerless and middleware-free — it relies only on SSH uploads and Nginx edits to make releases repeatable, rollbackable and fail-fast.

无需容器，现有裸机 / 虚拟机开箱即用。 No containers — your existing bare-metal / VM works out of the box.

它同时提供 命令行 与 桌面 GUI 两种入口：CLI 用 Click 编排流水线，适合接入 CI；GUI 基于 Tkinter，适合在本地可视化查看进度、状态与历史。两类产物（jar / static）与一键时间戳回滚，都开箱可用。 It ships both a CLI and a desktop GUI: the Click-based CLI fits CI; the Tkinter GUI visualizes progress, status and history locally. Two artifact types (jar / static) and one-click timestamped rollback work out of the box.

核心特性Core Features

为什么选 Keeploy Why Keeploy

🔐

密码纯本地 Local-only credentials

SSH 与 Nginx 密码统一存进 KeePass 数据库（.kdbx），运行时不写明文。四级回退：环境变量 → 配置文件 → keyfile → 交互输入。 SSH and Nginx passwords live in a KeePass database (.kdbx); nothing is written in plaintext. Fallback chain: env var → config file → keyfile → interactive input.

🌊

无感滚动发布 Zero-downtime rolling

逐台更新、至多一台离线；Nginx 自动注释 server 行摘流、换新后再恢复，用户全程无感知。 Updates host-by-host, at most one offline; Nginx auto-drains a node by commenting its server line, then restores — users never notice.

🐳

Dockerless 部署 Dockerless

无需 Docker / K8s / 镜像仓库。直接在宿主机操作：jar 走进程启停，static 走目录覆盖，流量切换靠 sed 改 Nginx。 No Docker / K8s / registry needed. Operates directly on the host: jar via process control, static via file overwrite, traffic via sed-edited Nginx.

⏪

一键回滚 One-click rollback

上线前自动按时间戳备份，出问题用同一份备份原样回退，干净利落。 Backups are auto-stamped before each release; on failure, the exact same backup is restored in one command.

🛑

Fail-Fast 安全中止 Fail-fast abort

任意一台失败时立即中止，并附上「如何手工恢复原状」的告警命令，绝不留下半残状态。 Aborts immediately on any host failure, printing the exact recovery commands so you never end up in a half-broken state.

🖥️

CLI + 桌面 GUI 双形态 CLI + Desktop GUI

命令行用 Click 编排流水线；也有 Tkinter 桌面 GUI，可视化查看进度、状态与历史。 Click-based CLI for the pipeline, plus a Tkinter desktop GUI to visualize progress, status and history.

工作原理How it works

六步，完成一次无感发布 Six steps to a seamless release

  1. 1

    本地打包上传 Build & upload locally

    按配置拉代码、打包，逐台 SFTP 上传到目标机。 Fetch code and package per config, then SFTP to each host one by one.

  2. 2

    Nginx 摘流 Drain the node

    用 sed 注释该机在 Nginx 的 server 行，nginx -t 校验后 nginx -s reload。 Comment the host server line with sed, verify with nginx -t, then nginx -s reload.

  3. 3

    等待排空 Wait for drain

    留出 drain_seconds，让在途连接自然结束，不再接收新请求。 Wait drain_seconds so in-flight connections finish and no new traffic arrives.

  4. 4

    停服替换启服 Stop, swap, start

    对 jar 启停进程、对 static 覆盖目录，换上新版本。 For jar: restart the process; for static: overwrite the directory with the new build.

  5. 5

    健康检查 Health check

    访问 health_check 端点，确认返回 expect_status 后才放行。 Hit the health_check endpoint and only proceed once expect_status is returned.

  6. 6

    Nginx 恢复流量 Restore traffic

    取消注释 server 行并 reload，该机重新接入负载均衡。 Uncomment the server line and reload, bringing the host back into the load balancer.

快速开始Quick Start

几条命令，跑通流水线 A few commands to run the pipeline 

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

# 准备配置（复制示例并填入你的主机 / KeePass）
cp config/example.json config/prod.json

# 先看一下当前各机状态
python main.py status -c config/prod.json

# 干跑一次，确认流程无误（不真正上线）
python main.py deploy --dry-run -c config/prod.json

# 正式发布（可只发部分主机 / 应用）
python main.py deploy -c config/prod.json --hosts web-01,web-02

# 想用图形界面？直接启动桌面 GUI
python keeploy_gui.py

还支持 --apps 按应用过滤、--skip-package 跳过打包、--companion-restart 联动重启依赖服务，以及 resume 断点续发。 Also supports --apps to filter by app, --skip-package to skip building, --companion-restart for dependent services, and resume to continue an interrupted run.

横向对比Compare

Keeploy 站在哪 Where Keeploy stands

手动 SSHManual SSH JenkinsJenkins AnsibleAnsible KeeployKeeploy
是否要 DockerNeeds Docker 否No 常依赖Often 否No 否（Dockerless）No (Dockerless)
凭据是否明文Plaintext creds 易泄露Leaky 存凭证库Vault 依赖 VaultVault KeePass 本地Local KeePass
无感滚动Rolling deploy 手搓脚本By hand 插件实现Plugin 需编排Needs setup 内置自动Built-in
一键回滚Rollback 无None 需配置Config 需规划Planned 时间戳备份Timestamped
是否带桌面 GUIDesktop GUI 无None Web 控制台Web 无None Tkinter GUITkinter
技术栈Tech Stack

用什么造的 Built with

Python 3.8+ClickTkinterpykeepassParamikoSQLiteAstro 5MIT License
K

来，给上线一个安心的姿势 Ship with peace of mind

Keeploy 已经开源。给一个 Star，Fork 一份，把无感滚动发布搬进你的下一次上线。 Keeploy is open source. Give it a Star, fork it, and bring zero-downtime rolling into your next release.

★ 去 GitHub 看看★ View on GitHub

← 返回作品集← Back to works