Metadata-Version: 2.4
Name: hostweaver
Version: 0.1.0
Summary: 远程部署与状态管理工具 - Remote deployment and state management tool based on SSH/SFTP
Project-URL: Homepage, https://github.com/zsuroy/hostweaver
Project-URL: Repository, https://github.com/zsuroy/hostweaver.git
Project-URL: Documentation, https://github.com/zsuroy/hostweaver#readme
Project-URL: Bug Tracker, https://github.com/zsuroy/hostweaver/issues
Author-email: HostWeaver <suroy@qq.com>
License-File: LICENSE
Keywords: automation,deployment,devops,remote-execution,sftp,ssh,systemd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: paramiko>=3.4.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.15.6; extra == 'dev'
Description-Content-Type: text/markdown

# HostWeaver

[![PyPI version](https://img.shields.io/pypi/v/hostweaver.svg)](https://pypi.org/project/hostweaver/)
[![Python version](https://img.shields.io/pypi/pyversions/hostweaver.svg)](https://pypi.org/project/hostweaver/)
[![License](https://img.shields.io/pypi/l/hostweaver.svg)](https://github.com/suroy/hostweaver/blob/main/LICENSE)

远程部署与状态管理工具 - 基于 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](https://typer.tiangolo.com/) 和 [rich](https://rich.readthedocs.io/) 的终端体验

## 📦 安装

```bash
# 使用 pip 安装
pip install hostweaver

# 使用 uv 安装
uv pip install hostweaver

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

## 🚀 快速开始

### 命令行使用

```bash
# 部署单个二进制文件
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 使用

#### 单机部署

```python
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}")
```

#### 多机并发部署

```python
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 连接

## 📚 更多文档

- 📖 [开发指南](docs/DEVELOPMENT.md) - 面向开发者的详细文档
- 📝 [示例代码](examples/) - 完整的使用示例
- 📋 [更新日志](CHANGELOG.md) - 版本更新记录
- 🚀 [发布指南](RELEASE.md) - 发布流程说明

## 🤝 贡献

欢迎提交 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](LICENSE) 文件

## 🙏 致谢

感谢以下开源项目：

- [paramiko](https://www.paramiko.org/) - SSH 协议实现
- [typer](https://typer.tiangolo.com/) - CLI 框架
- [rich](https://rich.readthedocs.io/) - 终端美化库
