na-tools 1.0.1__tar.gz

na_tools-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+
+jobs:
+  release:
+    name: Build and Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Build project
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

na_tools-1.0.1/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

na_tools-1.0.1/.python-version

@@ -0,0 +1 @@
+3.13

na_tools-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NekroAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

na_tools-1.0.1/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: na-tools
+Version: 1.0.1
+Summary: Nekro Agent 跨平台自动部署 CLI 工具
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# NA-Tools
+
+**Nekro Agent 跨平台自动部署 CLI 工具**
+
+支持 macOS / Linux，提供一键安装、更新、备份、恢复和配置管理。
+
+## 安装
+
+```bash
+# 需要 Python 3.10+
+pip install -e .
+
+# 或使用 uv
+uv sync
+```
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `na-tools install` | 安装 Nekro Agent（Docker 检测 → 配置 → 部署） |
+| `na-tools update` | 更新服务到最新版本 |
+| `na-tools backup` | 备份数据和配置 |
+| `na-tools restore [file]` | 从备份恢复（不指定文件则从列表选择） |
+| `na-tools config` | 快捷配置 nekro-agent.yaml |
+| `na-tools status` | 查看服务状态 |
+| `na-tools logs [service]` | 查看服务日志 |
+| `na-tools list` | 列出所有已安装的 Nekro Agent 及序号 |
+| `na-tools use <id/path>` | 切换当前激活的数据目录 |
+
+## 快速开始
+
+```bash
+# 一键安装
+na-tools install
+
+# 配置模型 API
+na-tools config model
+
+# 添加管理员
+na-tools config admin --add 12345678
+
+# 更新到最新版
+na-tools update
+
+# 备份数据
+na-tools backup
+
+# 恢复备份（交互式选择）
+na-tools restore
+
+# 查看多开或所有安装实例
+na-tools list
+
+# 切换到另一个安装实例
+na-tools use 1
+
+# 查看状态
+na-tools status
+```
+
+## 跨平台支持
+
+| 功能 | Linux | macOS |
+|------|-------|-------|
+| Docker 安装 | ✅ 自动 | ⚠️ 引导 |
+| 服务部署 | ✅ | ✅ |
+| 备份恢复 | ✅ | ✅ |
+| 配置管理 | ✅ | ✅ |

na_tools-1.0.1/README.md

@@ -0,0 +1,69 @@
+# NA-Tools
+
+**Nekro Agent 跨平台自动部署 CLI 工具**
+
+支持 macOS / Linux，提供一键安装、更新、备份、恢复和配置管理。
+
+## 安装
+
+```bash
+# 需要 Python 3.10+
+pip install -e .
+
+# 或使用 uv
+uv sync
+```
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `na-tools install` | 安装 Nekro Agent（Docker 检测 → 配置 → 部署） |
+| `na-tools update` | 更新服务到最新版本 |
+| `na-tools backup` | 备份数据和配置 |
+| `na-tools restore [file]` | 从备份恢复（不指定文件则从列表选择） |
+| `na-tools config` | 快捷配置 nekro-agent.yaml |
+| `na-tools status` | 查看服务状态 |
+| `na-tools logs [service]` | 查看服务日志 |
+| `na-tools list` | 列出所有已安装的 Nekro Agent 及序号 |
+| `na-tools use <id/path>` | 切换当前激活的数据目录 |
+
+## 快速开始
+
+```bash
+# 一键安装
+na-tools install
+
+# 配置模型 API
+na-tools config model
+
+# 添加管理员
+na-tools config admin --add 12345678
+
+# 更新到最新版
+na-tools update
+
+# 备份数据
+na-tools backup
+
+# 恢复备份（交互式选择）
+na-tools restore
+
+# 查看多开或所有安装实例
+na-tools list
+
+# 切换到另一个安装实例
+na-tools use 1
+
+# 查看状态
+na-tools status
+```
+
+## 跨平台支持
+
+| 功能 | Linux | macOS |
+|------|-------|-------|
+| Docker 安装 | ✅ 自动 | ⚠️ 引导 |
+| 服务部署 | ✅ | ✅ |
+| 备份恢复 | ✅ | ✅ |
+| 配置管理 | ✅ | ✅ |

na_tools-1.0.1/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "na-tools"
+version = "1.0.1"
+description = "Nekro Agent 跨平台自动部署 CLI 工具"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["click>=8.1", "rich>=13.0", "httpx>=0.27", "pyyaml>=6.0"]
+
+[project.scripts]
+na-tools = "na_tools.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/na_tools"]

na_tools-1.0.1/src/na_tools/__init__.py

@@ -0,0 +1,3 @@
+"""NA-Tools: Nekro Agent 跨平台自动部署 CLI 工具"""
+
+__version__ = "1.0.1"

na_tools-1.0.1/src/na_tools/__main__.py

@@ -0,0 +1,6 @@
+"""NA-Tools 入口模块。"""
+
+from na_tools.cli import main
+
+if __name__ == "__main__":
+    main()

na_tools-1.0.1/src/na_tools/cli.py

@@ -0,0 +1,39 @@
+"""NA-Tools CLI 入口。"""
+
+import click
+
+from . import __version__
+from .commands.backup import backup
+from .commands.config_cmd import config
+from .commands.install import install
+from .commands.logs import logs
+from .commands.restore import restore
+from .commands.status import status
+from .commands.update import update
+from .commands.use import use
+from .commands.list_cmd import list_cmd
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="na-tools")
+def main() -> None:
+    """NA-Tools: Nekro Agent 部署管理工具
+
+    支持一键安装、更新、备份、恢复和配置管理。
+    """
+    pass
+
+
+main.add_command(install)
+main.add_command(update)
+main.add_command(backup)
+main.add_command(restore)
+main.add_command(config)
+main.add_command(status)
+main.add_command(logs)
+main.add_command(use)
+main.add_command(list_cmd)
+
+
+if __name__ == "__main__":
+    main()

na_tools-1.0.1/src/na_tools/commands/backup.py

@@ -0,0 +1,218 @@
+"""backup 命令：备份 Nekro Agent 数据。"""
+
+import tarfile
+from datetime import datetime
+from pathlib import Path
+
+import click
+
+from ..core.compose import compose_exists
+from ..core.docker import DockerEnv
+from ..core.platform import default_data_dir
+from ..utils.privilege import with_sudo_fallback
+from ..utils.console import error, info, success, warning
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+@with_sudo_fallback
+@click.option("--data-dir", type=click.Path(), default=None, help="数据目录路径")
+@click.option(
+    "--output", "-o", type=click.Path(), default=None, help="备份文件输出路径"
+)
+@click.option("--no-restart", is_flag=True, default=False, help="备份后不重启服务")
+def backup(
+    ctx: click.Context, data_dir: str | None, output: str | None, no_restart: bool
+) -> None:
+    """备份 Nekro Agent 数据和配置。"""
+    if ctx.invoked_subcommand is not None:
+        return
+
+    data_dir_path = Path(data_dir or default_data_dir()).expanduser().resolve()
+
+    if not data_dir_path.exists():
+        error(f"数据目录不存在: {data_dir_path}")
+        raise click.Abort()
+
+    docker = DockerEnv()
+    env_path = data_dir_path / ".env"
+
+    # 生成备份文件名
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    if output:
+        backup_path = Path(output)
+    else:
+        backup_dir = Path("~/.config/na-tools/backup").expanduser() / data_dir_path.name
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        backup_path = backup_dir / f"{data_dir_path.name}_backup_{timestamp}.tar.gz"
+
+    backup_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 准备备份存储卷（在停止服务前解析卷名）
+    volume_backups_map: list[
+        tuple[str, str, Path]
+    ] = []  # (volume_name, backup_filename, backup_path)
+    volumes_dir = data_dir_path / "volumes_backup_tmp"
+
+    if compose_exists(data_dir_path) and docker.compose_installed:
+        config = docker.get_compose_config(
+            cwd=data_dir_path, env_file=env_path if env_path.exists() else None
+        )
+        if config and "services" in config and isinstance(config["services"], dict):
+            from typing import cast
+
+            services = cast(dict[str, dict[str, object]], config["services"])
+
+            # 映射关系: 服务名 -> 内部挂载点 -> 备份文件名
+            backup_targets = {
+                "nekro_postgres": ("/var/lib/postgresql/data", "postgres.tar.gz"),
+                "nekro_qdrant": ("/qdrant/storage", "qdrant.tar.gz"),
+            }
+
+            for svc_name, (internal_path, filename) in backup_targets.items():
+                if svc_name in services:
+                    # 尝试解析卷名
+                    real_volume_name = docker.get_service_volume(
+                        cwd=data_dir_path,
+                        service=svc_name,
+                        target=internal_path,
+                        env_file=env_path if env_path.exists() else None,
+                    )
+
+                    # 如果解析失败（容器未运行？），尝试从配置读取
+                    if not real_volume_name:
+                        svc_config = services[svc_name]
+                        volumes_config = svc_config.get("volumes", [])
+                        if isinstance(volumes_config, list):
+                            volumes = cast(list[dict[str, str]], volumes_config)
+                            for vol in volumes:
+                                if not vol:
+                                    continue
+                                if (
+                                    vol.get("type") == "volume"
+                                    and vol.get("target") == internal_path
+                                ):
+                                    real_volume_name = vol.get("source")
+                                    break
+
+                    if real_volume_name:
+                        volume_backups_map.append(
+                            (real_volume_name, filename, volumes_dir / filename)
+                        )
+
+    # 停止服务
+    should_restart = False
+    if compose_exists(data_dir_path) and docker.compose_installed:
+        info("正在停止服务以确保数据一致性...")
+        _ = docker.down(
+            cwd=data_dir_path, env_file=env_path if env_path.exists() else None
+        )
+        should_restart = True
+
+    # 执行卷备份
+    volume_backups: list[Path] = []
+    if volume_backups_map:
+        volumes_dir.mkdir(exist_ok=True)
+        for vol_name, filename, backup_file in volume_backups_map:
+            info(f"正在备份存储卷 {vol_name}...")
+
+            # 使用 alpine 打包
+            success_backup = docker.run_ephemeral(
+                image="alpine:latest",
+                cmd=["tar", "czf", f"/backup/{filename}", "-C", "/data", "."],
+                volumes={vol_name: "/data", str(volumes_dir): "/backup"},
+            )
+
+            if success_backup:
+                volume_backups.append(backup_file)
+                success(f"卷备份完成: {filename}")
+            else:
+                error(f"卷备份失败: {vol_name}")
+
+    # 打包数据
+    info(f"正在备份数据到: {backup_path}")
+    try:
+        with tarfile.open(backup_path, "w:gz") as tar:
+            # 添加主数据目录
+            tar.add(
+                data_dir_path,
+                arcname=data_dir_path.name,
+                filter=lambda x: None if "volumes_backup_tmp" in x.name else x,
+            )
+
+            # 添加卷备份
+            if volume_backups:
+                # 在 tar 中创建一个 volumes 目录
+                for vb in volume_backups:
+                    tar.add(vb, arcname=f"volumes/{vb.name}")
+
+        success(
+            f"备份完成: {backup_path} ({backup_path.stat().st_size / 1024 / 1024:.1f} MB)"
+        )
+    except Exception as e:
+        error(f"备份失败: {e}")
+        # 即使备份失败也要尝试重启
+        if should_restart and not no_restart:
+            info("正在重新启动服务...")
+            _ = docker.up(
+                cwd=data_dir_path, env_file=env_path if env_path.exists() else None
+            )
+        raise click.Abort()
+    finally:
+        # 清理临时卷备份目录
+        import shutil
+
+        if volumes_dir.exists():
+            shutil.rmtree(volumes_dir)
+
+    # 重启服务
+    if should_restart and not no_restart:
+        info("正在重新启动服务...")
+        if docker.up(
+            cwd=data_dir_path, env_file=env_path if env_path.exists() else None
+        ):
+            success("服务已重新启动。")
+        else:
+            warning("服务重启失败，请手动启动。")
+
+    success("🎉 备份完成!")
+
+
+@backup.command("list")
+@click.pass_context
+def list_backups(ctx: click.Context) -> None:
+    """列出可用的备份文件。"""
+    data_dir = None
+    import typing
+
+    obj = typing.cast(object, ctx.obj)
+    if isinstance(obj, dict):
+        from typing import cast
+
+        obj_dict = cast(dict[str, object], obj)
+        val = obj_dict.get("data_dir")
+        if isinstance(val, str):
+            data_dir = val
+    data_dir_path = Path(data_dir or default_data_dir()).expanduser().resolve()
+    backup_dir = Path("~/.config/na-tools/backup").expanduser() / data_dir_path.name
+
+    if not backup_dir.exists():
+        info("备份目录不存在或为空。")
+        return
+
+    backups = sorted(
+        list(backup_dir.glob("*.tar.gz")),
+        key=lambda x: x.stat().st_mtime,
+        reverse=True,
+    )
+
+    if not backups:
+        info("没有任何历史备份。")
+        return
+
+    info("发现以下历史备份：")
+    for i, b in enumerate(backups, 1):
+        mtime = datetime.fromtimestamp(b.stat().st_mtime).strftime("%Y-%m-%d %H:%M:%S")
+        click.echo(
+            f"  [{i}] {b.name} (备份时间: {mtime}, 大小: {b.stat().st_size / 1024 / 1024:.1f} MB)"
+        )