cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers bundled with Cancan Microstack."""

cancan_microstack/utils/container_env.py

@@ -0,0 +1,218 @@
+"""
+容器环境检测工具。
+Container environment detection utilities.
+
+自动检测当前环境使用的是 Docker 还是 Podman，并提供统一的命令接口。
+Automatically detect whether the runtime uses Docker or Podman and expose unified compose helpers.
+"""
+
+import shutil
+import subprocess
+from typing import Optional
+
+from linglong_web.utils import logger
+
+
+class ContainerEnv:
+    """
+    容器环境管理器。
+    Container environment manager responsible for lazy detection and caching results.
+    """
+
+    _detected_engine: Optional[str] = None
+    _detected_compose_cmd: Optional[str] = None
+
+    @classmethod
+    def detect_engine(cls) -> str:
+        """
+        检测容器引擎类型。
+        Detect container engine type and cache the decision.
+
+        Returns:
+            "podman" 或 "docker" / either "podman" or "docker".
+        """
+
+        if cls._detected_engine:
+            return cls._detected_engine
+
+        # 优先检测 Podman / prefer Podman first for local dev parity
+        if shutil.which("podman"):
+            try:
+                result = subprocess.run(
+                    ["podman", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    logger.info("Detected Podman: %s", result.stdout.strip())
+                    cls._detected_engine = "podman"
+                    return "podman"
+            except Exception as exc:  # noqa: BLE001 - log unexpected detection errors
+                logger.warning("Failed to verify podman: %s", exc)
+
+        # 其次检测 Docker / fallback to Docker detection
+        if shutil.which("docker"):
+            try:
+                result = subprocess.run(
+                    ["docker", "--version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    logger.info("Detected Docker: %s", result.stdout.strip())
+                    cls._detected_engine = "docker"
+                    return "docker"
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Failed to verify docker: %s", exc)
+
+        # 默认返回 docker / Default to docker
+        logger.warning("No container engine detected, defaulting to docker")
+        cls._detected_engine = "docker"
+        return "docker"
+
+    @classmethod
+    def detect_compose_command(cls) -> str:
+        """
+        检测 Compose 命令。
+        Detect compose command (docker compose, docker-compose, podman compose, etc.).
+
+        Returns:
+            完整命令字符串 / composed command name string.
+        """
+
+        if cls._detected_compose_cmd:
+            return cls._detected_compose_cmd
+
+        engine = cls.detect_engine()
+
+        if engine == "podman":
+            # Podman 环境：优先 podman-compose，其次 podman compose
+            if shutil.which("podman-compose"):
+                try:
+                    result = subprocess.run(
+                        ["podman-compose", "--version"],
+                        capture_output=True,
+                        text=True,
+                        timeout=5,
+                        check=False,
+                    )
+                    if result.returncode == 0:
+                        logger.info("Using podman-compose: %s", result.stdout.strip())
+                        cls._detected_compose_cmd = "podman-compose"
+                        return "podman-compose"
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("Failed to verify podman-compose: %s", exc)
+
+            # 尝试 podman compose（Podman 4.0+ 内置）
+            try:
+                result = subprocess.run(
+                    ["podman", "compose", "version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    logger.info("Using podman compose: %s", result.stdout.strip())
+                    cls._detected_compose_cmd = "podman compose"
+                    return "podman compose"
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Failed to verify podman compose: %s", exc)
+        else:
+            # Docker 环境：优先 docker compose（v2），其次 docker-compose（v1）
+            try:
+                result = subprocess.run(
+                    ["docker", "compose", "version"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                    check=False,
+                )
+                if result.returncode == 0:
+                    logger.info("Using docker compose: %s", result.stdout.strip())
+                    cls._detected_compose_cmd = "docker compose"
+                    return "docker compose"
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Failed to verify docker compose: %s", exc)
+
+            if shutil.which("docker-compose"):
+                try:
+                    result = subprocess.run(
+                        ["docker-compose", "--version"],
+                        capture_output=True,
+                        text=True,
+                        timeout=5,
+                        check=False,
+                    )
+                    if result.returncode == 0:
+                        logger.info("Using docker-compose: %s", result.stdout.strip())
+                        cls._detected_compose_cmd = "docker-compose"
+                        return "docker-compose"
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("Failed to verify docker-compose: %s", exc)
+
+        logger.warning("No compose command detected, defaulting to docker-compose")
+        cls._detected_compose_cmd = "docker-compose"
+        return "docker-compose"
+
+    @classmethod
+    def get_compose_command_list(cls, compose_file: str, project_name: str) -> list[str]:
+        """
+        获取 compose 命令的基础命令列表。
+        Build the command list for executing compose operations.
+
+        Args:
+            compose_file: compose 文件路径 / compose file path.
+            project_name: 项目名称 / compose project name.
+
+        Returns:
+            命令列表，如 ["podman-compose", "-f", "xxx.yml", "-p", "project"]。
+        """
+
+        compose_cmd = cls.detect_compose_command()
+        cmd_parts = compose_cmd.split()
+        return cmd_parts + ["-f", compose_file, "-p", project_name]
+
+    @classmethod
+    def get_info(cls) -> dict[str, str | bool]:
+        """
+        获取容器环境信息。
+        Return a summary dict of the detected container environment.
+        """
+
+        engine = cls.detect_engine()
+        compose_cmd = cls.detect_compose_command()
+        return {
+            "engine": engine,
+            "compose_command": compose_cmd,
+            "is_podman": engine == "podman",
+            "is_docker": engine == "docker",
+        }
+
+
+def get_container_engine() -> str:
+    """获取容器引擎类型 / Expose detected container engine."""
+
+    return ContainerEnv.detect_engine()
+
+
+def get_compose_command() -> str:
+    """获取 compose 命令 / Expose detected compose command."""
+
+    return ContainerEnv.detect_compose_command()
+
+
+def is_podman_env() -> bool:
+    """判断是否为 Podman 环境 / Return True when Podman is available."""
+
+    return ContainerEnv.detect_engine() == "podman"
+
+
+def is_docker_env() -> bool:
+    """判断是否为 Docker 环境 / Return True when Docker is available."""
+
+    return ContainerEnv.detect_engine() == "docker"

cancan_microstack-0.0.1.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: cancan-microstack
+Version: 0.0.1
+Summary: Controllersrv/Infrasrv/Opsbffsrv bundle with compose tooling
+Author-email: Victor Lai <victor.lai@foxmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/10000ms/cancan_microstack
+Project-URL: Repository, https://github.com/10000ms/cancan_microstack
+Project-URL: Bug Tracker, https://github.com/10000ms/cancan_microstack/issues
+Keywords: fastapi,microservices,docker,compose,orchestration,workflow,ops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Systems Administration
+Classifier: Framework :: FastAPI
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml<7.0.0,>=6.0.0
+Requires-Dist: bcrypt<6.0.0,>=4.0.0
+Requires-Dist: pyotp<3.0.0,>=2.9.0
+Requires-Dist: Pillow<13.0.0,>=10.0.0
+Requires-Dist: nanoid<4.0.0,>=2.0.0
+Requires-Dist: redis[hiredis]<9.0.0,>=5.0.0
+Requires-Dist: cryptography<50.0.0,>=41.0.0
+Requires-Dist: qrcode<9.0.0,>=7.4.0
+Requires-Dist: jinja2<4.0.0,>=3.1.0
+Requires-Dist: geoip2<6.0.0,>=4.7.0
+Requires-Dist: jmespath<2.0.0,>=1.0.0
+Requires-Dist: dragonfly-container[all]>=0.0.1
+Requires-Dist: linglong-web[all]>=0.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# Cancan Microstack
+
+[![PyPI](https://img.shields.io/pypi/v/cancan-microstack.svg?color=8b7cff)](https://pypi.org/project/cancan-microstack/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+可嵌入的基础设施微服务栈：把一整套基础设施微服务（`controllersrv` / `infrasrv` / `opsbffsrv`）连同 Docker Compose 编排、DDL、运维前端与统一 CLI，打包成**一个可 pip 安装的 Python 库**，让业务仓库“只写业务代码”。
+
+An embeddable infrastructure microstack: bundle a complete set of infrastructure microservices (`controllersrv` / `infrasrv` / `opsbffsrv`) — together with Docker Compose orchestration, DDL, an ops UI and a unified CLI — into **a single pip-installable Python library**, so your product repo contains business logic only.
+
+> 📖 **完整文档 / Full documentation**：[`docs/index.html`](docs/index.html) — 双语、含架构原理、CLI 参考与使用说明。
+> Bilingual docs with architecture, CLI reference and guides.
+
+> **定位 / Positioning**：本库只包含**通用基础设施能力**；具体业务服务与逻辑应留在你自己的业务仓库。
+> This library contains **generic infrastructure capabilities only**; your business services and logic stay in your own product repo.
+
+## 特性 / Features
+
+- 🛠️ **统一 CLI / Unified CLI**：`cancan` 命令提供 `assets` / `compose` / `services` / `stack` 子命令。
+- 🔀 **Compose 构建器 / Compose builder**：把内置 infra compose 与业务 compose、override 深度合并成一个可运行栈。
+  Deep-merge the built-in infra compose with your services compose and overrides into one runnable stack.
+- 🔌 **免 Fork 覆盖 / Fork-free overrides**：用 `cancan_overrides/` 只替换你想改的文件，其余复用库实现。
+- 🖥️ **内置运维前端 / Bundled ops UI**：随库附带 adminops UI 构建产物，可导出由 Caddy 挂载。
+- 🗄️ **自管理 DDL / Self-managed DDL**：infra/ops 数据库表随服务启动自动初始化。
+- ♻️ **整栈生命周期 / Full-stack lifecycle**：`stack up/down/status` 同时管理宿主机进程与容器栈。
+
+构建于已发布的姊妹库之上 / Built on published sibling libraries：[`linglong-web`](https://pypi.org/project/linglong-web/) · [`dragonfly-container`](https://pypi.org/project/dragonfly-container/)。
+
+## 快速开始 / Quick Start
+
+```bash
+# 1. 安装 / Install
+pip install cancan-microstack
+
+# 2. 脚手架：生成最小可跑工作区（业务 compose 样例 + .env + overrides 骨架）
+#    Scaffold a minimal workspace (services compose sample + .env + overrides skeleton)
+cancan init
+
+# 3. 预检环境（容器引擎 / 端口 / 配置 / 弱默认值）
+#    Pre-flight checks (engine / ports / config / weak defaults)
+cancan doctor
+
+# 4. 一键启动整套集群（推荐）/ Bring up the whole stack
+#    生成 compose.cancan.yml、bootstrap 运行文件、宿主机起 controllersrv、容器栈 up
+cancan stack up --workspace . --service-file docker-compose.services.yml
+
+# 5. 状态 / 关闭 — status / teardown
+cancan stack status --workspace .
+cancan stack down   --workspace .
+```
+
+> 安装即提供 `cancan` 命令；也可用 `python -m cancan_microstack.cli ...`。
+> Installing provides the `cancan` command; `python -m cancan_microstack.cli ...` works too.
+>
+> 运行容器栈需要 Docker 或 Podman。 / Running the stack requires Docker or Podman.
+
+> ⚠️ **生产安全 / Production safety**：凭据与密钥集中在工作区 `.env`（`cancan init` 会生成，并自动写入一个唯一的 TOTP 加密 key）。其中数据库等使用本地开发弱默认值（如 `admin123`）以便开箱即用。**生产部署务必在 `.env` 里改成真实凭证；`cancan doctor` 会提示仍在使用的弱默认值。**
+> Credentials & secrets live in the workspace `.env` (created by `cancan init`, with a unique TOTP encryption key auto-generated). Databases use weak local-dev defaults (e.g. `admin123`) for out-of-the-box use. **In production, set real secrets in `.env`; `cancan doctor` flags any weak defaults still in use.**
+
+## CLI 速览 / CLI at a glance
+
+| 命令 / Command | 作用 / Purpose |
+| --- | --- |
+| `cancan init` | 脚手架最小可跑工作区 / scaffold a minimal runnable workspace |
+| `cancan doctor` | 起栈前环境/配置预检 / pre-flight environment & config checks |
+| `cancan assets list [subdir]` | 列出内置资产 / list bundled assets |
+| `cancan assets export <name> <dest> [--overwrite]` | 导出资产到工作区 / export an asset to the workspace |
+| `cancan compose build [--service-file …] [--override …]` | 合成 `compose.cancan.yml` / synthesize the stack file |
+| `cancan services run <name> [--host] [--port]` | 前台运行内置服务 / run a bundled service in the foreground |
+| `cancan stack up/down/status` | 整栈生命周期（宿主机进程 + 容器栈）/ full-stack lifecycle |
+
+完整参数与原理见 [`docs/index.html`](docs/index.html)。 / Full options and design in the docs.
+
+## 内置服务 / Bundled services
+
+| 服务 / Service | 职责 / Responsibility |
+| --- | --- |
+| `controllersrv` | 宿主机进程，封装 Docker/Podman 容器操作（基于 `dragonfly-container`）/ host process managing containers |
+| `infrasrv` | 服务注册、工作流引擎与调度、日志采集、健康检查 / registry, workflow, log ingestion, health checks |
+| `opsbffsrv` | 运维 BFF：为 adminops 前端聚合接口（认证 / Caddy / DB / 日志）/ ops BFF for the admin UI |
+
+服务配置基于 `linglong-web`，资源（PostgreSQL / Redis / MongoDB / RabbitMQ / Celery）由其统一编排。
+Services are configured via `linglong-web`, which orchestrates the backing resources.
+
+## 免 Fork 覆盖 / Fork-free overrides
+
+在工作区放一个 `cancan_overrides/<service>/` 目录，只放你要替换的文件，运行时会优先加载它，其余仍复用库实现（也可用环境变量 `CANCAN_OVERRIDE_ROOT` 指定）。
+
+Drop a `cancan_overrides/<service>/` directory in your workspace with only the files you want to replace; it is loaded with priority at runtime while the rest falls back to the library (or point at it via `CANCAN_OVERRIDE_ROOT`).
+
+## 运维前端（adminops）/ The adminops UI
+
+库内**只包含前端的构建产物**（`assets/www/adminops/`），不含前端源码。前端源码在独立仓库维护；更新流程：在前端源码仓构建（`pnpm build`）→ 把 `dist` 产物覆盖到 `assets/www/adminops/` → 重新发布本库。
+
+This library ships **only the built frontend artifacts** (`assets/www/adminops/`), not the frontend source. The UI source lives in a separate repository; to update: build in the source repo (`pnpm build`) → copy the `dist` output into `assets/www/adminops/` → re-release this library.
+
+## 开发 / Development
+
+```bash
+git clone https://github.com/10000ms/cancan_microstack.git
+cd cancan_microstack
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## 许可证 / License
+
+MIT License © 2026 Victor Lai