HostWeaver

远程部署与状态管理工具 - 基于 SSH/SFTP 的自动化部署引擎

Remote deployment and state management tool based on SSH/SFTP.

✨ 功能特性

• 🔐 SSH/SFTP 封装 - 支持密码和私钥认证，连接池管理
• 📦 文件传输 - 可靠的文件上传/下载，自动赋予执行权限（chmod +x）
• ⚙️ Systemd 管理 - 动态生成 .service 配置文件，完整生命周期管理（start/stop/restart/status）
• 🔑 License 生成 - 基于机器指纹（/etc/machine-id）的授权密钥生成
• 🚀 一键部署 - 完整的部署工作流，支持进度显示
• 🖥️ 多机并发 - 批量部署支持，失败隔离，汇总报告
• 🎨 优雅 CLI - 基于 typer 和 rich 的终端体验

📦 安装

# 使用 pip 安装
pip install hostweaver

# 使用 uv 安装
uv pip install hostweaver

# 从源码安装（开发模式）
git clone https://github.com/zsuroy/hostweaver.git
cd hostweaver
uv pip install -e ".[dev]"

🚀 快速开始

命令行使用

# 部署单个二进制文件
hostweaver deploy \
    --host 192.168.1.100 \
    --username root \
    --key-file ~/.ssh/id_rsa \
    --source ./dist/app \
    --install-dir /opt/app \
    --service myapp \
    --env APP_ENV=production \
    --env APP_PORT=8000

# 部署整个项目目录
hostweaver deploy \
    --host 192.168.1.100 \
    --username root \
    --key-file ~/.ssh/id_rsa \
    --source ./project \
    --entrypoint main.py \
    --install-dir /opt/app \
    --service myapp

# 查询服务状态
hostweaver status \
    --host 192.168.1.100 \
    --username root \
    --service myapp

# 查看服务日志
hostweaver logs \
    --host 192.168.1.100 \
    --username root \
    --service myapp \
    --lines 50

# 重启服务
hostweaver restart \
    --host 192.168.1.100 \
    --username root \
    --service myapp

Python API 使用

单机部署

from hostweaver.business.generic_deployer import GenericDeployer
from hostweaver.workflow.single_deploy import SingleDeployWorkflow

# 创建部署器
deployer = GenericDeployer(
    host="192.168.1.100",
    username="root",
    pkey_path="~/.ssh/id_rsa",
    source_path="./dist/app",
    install_dir="/opt/app",
    service_name="myapp",
    env_vars={"APP_ENV": "production"},
    secret_key="your-secret-key",  # 用于生成 License
)

# 执行部署
workflow = SingleDeployWorkflow(deployer)
result = workflow.execute()

# 检查结果
if result.success:
    print(f"部署成功！机器指纹：{result.machine_id}")
else:
    print(f"部署失败：{result.message}")

多机并发部署

from hostweaver.business.generic_deployer import GenericDeployer
from hostweaver.concurrent.pool import DeployPool, HostConfig
from hostweaver.concurrent.reporter import DeploymentReporter

# 创建并发池
pool = DeployPool(max_workers=5)

# 添加主机
hosts = [
    HostConfig(host="192.168.1.100", username="root"),
    HostConfig(host="192.168.1.101", username="root"),
    HostConfig(host="192.168.1.102", username="root", env_vars={"NODE_ID": "3"}),
]

for config in hosts:
    pool.add_task(
        config=config,
        deployer_class=GenericDeployer,
        source_path="./dist/app",
        install_dir="/opt/app",
        service_name="myapp",
        secret_key="your-secret-key",
    )

# 执行部署
results = pool.execute()

# 生成报告
reporter = DeploymentReporter(results)
reporter.print_report(verbose=True)

# 获取汇总
summary = reporter.get_summary()
print(f"成功率：{summary['success_rate']:.1%}")

📖 核心概念

部署流程

HostWeaver 定义了一个标准的部署生命周期：

connect → pre_deploy() → run() → post_deploy() → disconnect

1. connect: 建立 SSH 连接，初始化 SFTP 和 Systemd 管理器
2. pre_deploy(): 部署前准备（获取机器指纹、停止旧服务、生成 License）
3. run(): 执行部署（文件上传、配置渲染、systemd 重载）
4. post_deploy(): 部署后处理（启动服务、验证状态、输出日志）
5. disconnect: 断开 SSH 连接

📚 更多文档

• 📖 开发指南 - 面向开发者的详细文档
• 📝 示例代码 - 完整的使用示例
• 📋 更新日志 - 版本更新记录
• 🚀 发布指南 - 发布流程说明

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 License

MIT License - 详见 LICENSE 文件

🙏 致谢

感谢以下开源项目：

• paramiko - SSH 协议实现
• typer - CLI 框架
• rich - 终端美化库