cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/cmd/__init__.py

@@ -0,0 +1,54 @@
+"""Cancan microstack service entrypoints under cmd/.
+
+该目录用于放置 cancan_microstack 内置服务启动入口（controllersrv/infrasrv/opsbffsrv）。
+This directory hosts builtin service entrypoints (controllersrv/infrasrv/opsbffsrv).
+
+⚠️ 注意 / Note:
+Python 标准库也有一个名为 `cmd` 的模块，pytest/pdb 会依赖其中的 `Cmd`。
+当开发者在源码目录下运行（例如直接在 cancan_microstack 仓库根目录执行 pytest）时，
+同名目录 `cmd/` 会遮蔽标准库模块，导致 pytest 在启动阶段崩溃。
+
+为保证：
+- 仍保留 `cancan_microstack.cmd.*` 入口结构 / keep entrypoints importable
+- 同时 `import cmd; cmd.Cmd` 仍指向标准库实现 / keep stdlib cmd symbols available
+
+这里做一个轻量桥接：从标准库路径加载 `cmd.py` 并暴露必要符号。
+"""
+import importlib.util
+import sysconfig
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_stdlib_cmd_module() -> ModuleType:
+	"""加载标准库 cmd 模块（避免被当前包遮蔽）。
+	Load stdlib cmd module without being shadowed by this package.
+	"""
+
+	stdlib_dir = sysconfig.get_path("stdlib")
+	if not stdlib_dir:
+		raise RuntimeError("Unable to locate stdlib path / 无法定位标准库路径")
+
+	cmd_py_path = Path(stdlib_dir) / "cmd.py"
+	if not cmd_py_path.exists():
+		raise RuntimeError(f"Stdlib cmd.py not found at: {cmd_py_path}")
+
+	spec = importlib.util.spec_from_file_location("_stdlib_cmd", cmd_py_path)
+	if spec is None or spec.loader is None:
+		raise RuntimeError("Unable to load stdlib cmd spec / 无法加载标准库 cmd 模块 spec")
+
+	module = importlib.util.module_from_spec(spec)
+	spec.loader.exec_module(module)
+	return module
+
+
+_stdlib_cmd = _load_stdlib_cmd_module()
+
+# Expose stdlib symbols used by pdb/pytest.
+# 暴露 pdb/pytest 依赖的标准库符号。
+Cmd = _stdlib_cmd.Cmd  # type: ignore[attr-defined]
+
+__all__ = [
+	"Cmd",
+]
+

cancan_microstack/cmd/cancan/__init__.py

@@ -0,0 +1,12 @@
+"""cancan CLI module (library-owned).
+
+说明 / Notes:
+- 该目录属于 cancan_microstack（libs），用于提供宿主机侧的 CLI 能力。
+  This folder belongs to cancan_microstack (libs) and provides host-side CLI utilities.
+
+- 使用方仓库（consumer repo）不应长期保存框架 CLI 代码；应通过安装 libs 包或
+  使用 `python -m cancan_microstack.cmd.cancan.run` 调用。
+  Consumer repos should not permanently carry framework CLI code; use the installed package
+  or `python -m cancan_microstack.cmd.cancan.run`.
+"""
+__all__ = []

cancan_microstack/cmd/cancan/run.py

@@ -0,0 +1,395 @@
+"""cancan CLI entrypoint (library-owned).
+
+目标 / Goal:
+- controllersrv 在宿主机运行：提供 start/stop/status
+  controllersrv runs on host: start/stop/status
+- 集群通过 {engine} compose 启动/关闭：提供 cluster up/down
+  cluster via {engine} compose: cluster up/down
+- adminops 前端构建为静态 SPA 并发布到使用方工作区的 Caddy 静态目录
+    Build adminops frontend into static assets and publish to consumer workspace's Caddy static dir
+
+重要说明 / Important Notes:
+- 该 CLI 属于 libs（cancan_microstack），使用方仓库不应长期保存框架脚本。
+    This CLI belongs to libs (cancan_microstack); consumer repos should not keep framework scripts.
+- 所有路径均通过动态计算，禁止硬编码绝对路径。
+  All paths are resolved dynamically; do NOT hardcode absolute paths.
+"""
+import argparse
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+
+def _find_repo_root(start: Path) -> Path:
+    """尝试从 start 向上查找使用方仓库根目录 / Try to locate consumer repo root.
+
+    查找标记 / Markers:
+    - compose.cancan.yml
+    - docker-compose.yml
+    - pyproject.toml
+    """
+
+    start = start.resolve()
+    candidates = [start, *start.parents]
+
+    for base in candidates:
+        if (base / "compose.cancan.yml").exists():
+            return base
+        if (base / "docker-compose.yml").exists():
+            return base
+        if (base / "pyproject.toml").exists():
+            return base
+
+    return start
+
+
+def _runtime_dir(repo_root: Path) -> Path:
+    """运行时目录 / Runtime dir."""
+
+    runtime_dir = repo_root / ".runtime"
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    return runtime_dir
+
+
+def _pid_file(repo_root: Path) -> Path:
+    """controllersrv PID 文件路径 / controllersrv PID file path."""
+
+    return _runtime_dir(repo_root) / "controllersrv.pid"
+
+
+def _log_file(repo_root: Path) -> Path:
+    """controllersrv 日志文件路径 / controllersrv log file path."""
+
+    return _runtime_dir(repo_root) / "controllersrv.log"
+
+
+def _is_process_alive(pid: int) -> bool:
+    """判断进程是否存在 / Check whether a process exists."""
+
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _read_pid(repo_root: Path) -> Optional[int]:
+    """读取 PID / Read PID."""
+
+    pid_path = _pid_file(repo_root)
+    if not pid_path.exists():
+        return None
+
+    try:
+        pid = int(pid_path.read_text(encoding="utf-8").strip())
+    except Exception:
+        return None
+
+    return pid
+
+
+def controllersrv_status(repo_root: Path) -> int:
+    """打印 controllersrv 状态 / Print controllersrv status."""
+
+    pid = _read_pid(repo_root)
+    if pid is None:
+        print("controllersrv: stopped (no pid file)")
+        return 1
+
+    if _is_process_alive(pid):
+        print(f"controllersrv: running (pid={pid})")
+        return 0
+
+    print(f"controllersrv: stale pid file (pid={pid})")
+    return 2
+
+
+def controllersrv_start(repo_root: Path, host: str, port: int) -> int:
+    """启动 controllersrv（后台）/ Start controllersrv in background."""
+
+    pid = _read_pid(repo_root)
+    if pid is not None and _is_process_alive(pid):
+        print(f"controllersrv already running (pid={pid})")
+        return 0
+
+    # 清理陈旧 pid 文件 / Remove stale pid file
+    try:
+        _pid_file(repo_root).unlink(missing_ok=True)
+    except Exception:
+        pass
+
+    wrapper_script = repo_root / "cmd" / "controllersrv" / "run.py"
+    if not wrapper_script.exists():
+        print(f"controllersrv wrapper not found: {wrapper_script}")
+        print("Hint: in a consumer repo, cmd wrappers are usually generated by cancan build.")
+        return 2
+
+    log_path = _log_file(repo_root)
+    log_fp = open(log_path, "a", encoding="utf-8")
+
+    # 使用当前解释器启动（建议在 venv 下运行本脚本）
+    # Start using current interpreter (recommended: run this script under venv)
+    cmd = [sys.executable, "-u", str(wrapper_script)]
+
+    env = os.environ.copy()
+    env.setdefault("PYTHONUNBUFFERED", "1")
+
+    # 控制 host/port 通过环境变量传递。
+    # Pass host/port via env.
+    env["CONTROLLERSRV_HOST_BIND"] = host
+    env["CONTROLLERSRV_PORT_BIND"] = str(port)
+
+    proc = subprocess.Popen(
+        cmd,
+        cwd=str(repo_root),
+        env=env,
+        stdout=log_fp,
+        stderr=log_fp,
+        start_new_session=True,
+    )
+
+    _pid_file(repo_root).write_text(str(proc.pid), encoding="utf-8")
+    print(f"controllersrv started (pid={proc.pid}) log={log_path}")
+    return 0
+
+
+def controllersrv_stop(repo_root: Path, timeout_seconds: int = 10) -> int:
+    """停止 controllersrv / Stop controllersrv."""
+
+    pid = _read_pid(repo_root)
+    if pid is None:
+        print("controllersrv already stopped (no pid file)")
+        return 0
+
+    if not _is_process_alive(pid):
+        print(f"controllersrv already stopped (pid={pid})")
+        try:
+            _pid_file(repo_root).unlink(missing_ok=True)
+        except Exception:
+            pass
+        return 0
+
+    print(f"Stopping controllersrv (pid={pid}) ...")
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        _pid_file(repo_root).unlink(missing_ok=True)
+        print("controllersrv stopped")
+        return 0
+
+    deadline = time.time() + timeout_seconds
+    while time.time() < deadline:
+        if not _is_process_alive(pid):
+            _pid_file(repo_root).unlink(missing_ok=True)
+            print("controllersrv stopped")
+            return 0
+        time.sleep(0.2)
+
+    print("controllersrv did not stop in time; sending SIGKILL")
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+    _pid_file(repo_root).unlink(missing_ok=True)
+    return 0
+
+
+def _run_compose(repo_root: Path, compose_engine: str, compose_file: Path, args: list[str]) -> int:
+    """运行 compose 命令 / Run compose command."""
+
+    if compose_engine not in {"podman", "docker"}:
+        print(f"Unsupported compose engine: {compose_engine}")
+        return 2
+
+    cmd = [compose_engine, "compose", "-f", str(compose_file), *args]
+    print("Running:", " ".join(cmd))
+
+    proc = subprocess.run(cmd, cwd=str(repo_root))
+    return int(proc.returncode)
+
+
+def cluster_up(repo_root: Path, compose_engine: str, compose_file: Path) -> int:
+    """启动集群 / Bring up the cluster."""
+
+    rc = controllersrv_start(repo_root=repo_root, host="0.0.0.0", port=22100)
+    if rc != 0:
+        return rc
+
+    return _run_compose(repo_root, compose_engine, compose_file, ["up", "-d"])
+
+
+def cluster_down(repo_root: Path, compose_engine: str, compose_file: Path, keep_controllersrv: bool) -> int:
+    """关闭集群 / Bring down the cluster."""
+
+    rc = _run_compose(repo_root, compose_engine, compose_file, ["down"])
+    if keep_controllersrv:
+        return rc
+
+    stop_rc = controllersrv_stop(repo_root)
+    return rc if rc != 0 else stop_rc
+
+
+def adminops_build_and_publish(repo_root: Path, admin_root: Path, output_dir: Path) -> int:
+    """Build adminops and publish to output directory.
+
+        - 构建 adminops 前端工程
+            Build the adminops frontend project
+        - 拷贝 dist 到使用方工作区的 Caddy 静态目录
+            Copy dist into consumer workspace's Caddy static dir
+    """
+
+    if not admin_root.exists():
+        print(f"adminops UI source not found: {admin_root}")
+        return 2
+
+    pnpm = shutil.which("pnpm")
+    if not pnpm:
+        print("pnpm not found in PATH")
+        return 2
+
+    print(f"Building adminops UI at: {admin_root}")
+    build_proc = subprocess.run([pnpm, "-C", str(admin_root), "build"], check=False)
+    if build_proc.returncode != 0:
+        return int(build_proc.returncode)
+
+    dist_dir = admin_root / "dist"
+    if not dist_dir.exists():
+        print(f"Build output not found: {dist_dir}")
+        return 2
+
+    output_dir.parent.mkdir(parents=True, exist_ok=True)
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+
+    shutil.copytree(dist_dir, output_dir)
+    print(f"Published adminops to: {output_dir}")
+    print("Note: output directory is intended to be git-ignored.")
+    return 0
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="cancan", add_help=True)
+
+    parser.add_argument(
+        "--repo-root",
+        default=os.getenv("CANCAN_REPO_ROOT", ""),
+        help="consumer repo root / 使用方仓库根目录（默认自动探测）",
+    )
+
+    parser.add_argument(
+        "--engine",
+        default=os.getenv("CANCAN_COMPOSE_ENGINE", "podman"),
+        choices=["podman", "docker"],
+        help="compose engine / compose 引擎（默认 podman）",
+    )
+
+    parser.add_argument(
+        "--compose-file",
+        default=os.getenv("CANCAN_COMPOSE_FILE", ""),
+        help="compose file path / compose 文件路径（默认 repo_root/compose.cancan.yml）",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # controllersrv
+    controllersrv_parser = subparsers.add_parser("controllersrv", help="controllersrv lifecycle")
+    controllersrv_sub = controllersrv_parser.add_subparsers(dest="action", required=True)
+
+    start_parser = controllersrv_sub.add_parser("start", help="start controllersrv")
+    start_parser.add_argument("--host", default="0.0.0.0")
+    start_parser.add_argument("--port", type=int, default=22100)
+
+    stop_parser = controllersrv_sub.add_parser("stop", help="stop controllersrv")
+    stop_parser.add_argument("--timeout", type=int, default=10)
+
+    controllersrv_sub.add_parser("status", help="status controllersrv")
+
+    # cluster
+    cluster_parser = subparsers.add_parser("cluster", help="cluster up/down")
+    cluster_sub = cluster_parser.add_subparsers(dest="action", required=True)
+
+    cluster_sub.add_parser("up", help="compose up -d with controllersrv")
+
+    down_parser = cluster_sub.add_parser("down", help="compose down and stop controllersrv")
+    down_parser.add_argument(
+        "--keep-controllersrv",
+        action="store_true",
+        help="do not stop controllersrv / 不停止 controllersrv",
+    )
+
+    # adminops
+    admin_parser = subparsers.add_parser("adminops", help="adminops build/publish")
+    admin_sub = admin_parser.add_subparsers(dest="action", required=True)
+
+    build_parser = admin_sub.add_parser("build", help="build adminops and publish to Caddy dir")
+    build_parser.add_argument(
+        "--admin-root",
+        default=os.getenv("CANCAN_ADMIN_ROOT", ""),
+        help="adminops frontend root / 前端工程根目录（默认 repo_root 的同级目录）",
+    )
+    build_parser.add_argument(
+        "--output-dir",
+        default=os.getenv("CANCAN_ADMIN_OUTPUT_DIR", ""),
+        help="publish output dir / 发布输出目录（默认 repo_root/builds/caddy/www/adminops）",
+    )
+
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str]) -> int:
+    args = _parse_args(argv)
+
+    if args.repo_root:
+        repo_root = Path(args.repo_root).expanduser().absolute()
+    else:
+        repo_root = _find_repo_root(Path.cwd())
+
+    compose_file = Path(args.compose_file).expanduser().absolute() if args.compose_file else (repo_root / "compose.cancan.yml")
+
+    if args.command == "controllersrv":
+        if args.action == "start":
+            return controllersrv_start(repo_root=repo_root, host=args.host, port=args.port)
+        if args.action == "stop":
+            return controllersrv_stop(repo_root=repo_root, timeout_seconds=args.timeout)
+        if args.action == "status":
+            return controllersrv_status(repo_root)
+
+    if args.command == "cluster":
+        if args.action == "up":
+            return cluster_up(repo_root=repo_root, compose_engine=args.engine, compose_file=compose_file)
+        if args.action == "down":
+            return cluster_down(
+                repo_root=repo_root,
+                compose_engine=args.engine,
+                compose_file=compose_file,
+                keep_controllersrv=bool(args.keep_controllersrv),
+            )
+
+    if args.command == "adminops":
+        if args.action == "build":
+            admin_root = (
+                Path(args.admin_root).expanduser().absolute()
+                if args.admin_root
+                else repo_root.parent.absolute()
+            )
+            output_dir = (
+                Path(args.output_dir).expanduser().absolute()
+                if args.output_dir
+                else (repo_root / "builds" / "caddy" / "www" / "adminops")
+            )
+            return adminops_build_and_publish(repo_root=repo_root, admin_root=admin_root, output_dir=output_dir)
+
+    print("Unknown command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

cancan_microstack/cmd/controllersrv/run.py

@@ -0,0 +1,131 @@
+"""
+controllersrv 启动脚本
+
+这是一个特殊的服务，运行在宿主机上，负责管理 Docker Compose 集群。
+
+初始化流程：
+1. 初始化路由
+2. 初始化服务，挂载启动和关闭回调
+3. 启动服务
+
+启动回调 (`initialize_controllersrv`):
+1. 初始化服务验证器
+2. 初始化执行器
+3. 初始化并启动 Worker
+
+关闭回调 (`shutdown_controllersrv`):
+1. 优雅关闭 Worker
+"""
+import asyncio
+import os
+from typing import Optional
+
+from linglong_web.utils import logger
+from linglong_web import ServerRouter
+from linglong_web import LinglongConfig
+from dragonfly_container.core import ExecutorFactory
+from dragonfly_container.models.constants import ContainerEngine
+
+from cancan_microstack.public.web.server import AppServer
+
+from cancan_microstack.services.controllersrv.router import router_list
+from cancan_microstack.services.controllersrv.conf.config import service_conf_dict
+from cancan_microstack.services.controllersrv.domain.task import TaskWorker, set_task_worker
+from cancan_microstack.services.controllersrv.domain.service_validator import init_service_validator
+
+worker_instance: Optional[TaskWorker] = None
+
+
+async def initialize_controllersrv():
+    """
+    controllersrv 的启动回调函数（直接使用 Dragonfly Container UnifiedExecutor）
+    """
+    global worker_instance
+    logger.info("=" * 60)
+    logger.info("Starting controllersrv initialization")
+    logger.info("=" * 60)
+
+    # 1. 创建 UnifiedExecutor（自动检测 Docker 或 Podman）
+    # Create UnifiedExecutor (auto-detect Docker or Podman)
+    logger.info("Step 1: Creating Dragonfly Container UnifiedExecutor...")
+    compose_file = LinglongConfig.DOCKER_COMPOSE_FILE
+    project_name = LinglongConfig.DOCKER_COMPOSE_PROJECT_NAME
+    # engine 选择：默认 Docker-first auto-detect 可能在 macOS 上导致慢启动（Docker 未运行时会卡住）。
+    # Engine selection: Docker-first auto-detect may cause slow startup on macOS when Docker isn't running.
+    engine_env = (os.environ.get("CANCAN_CONTAINER_ENGINE") or "").strip().lower()
+    engine: ContainerEngine | None = None
+    if engine_env in {"podman"}:
+        engine = ContainerEngine.PODMAN
+    elif engine_env in {"docker"}:
+        engine = ContainerEngine.DOCKER
+
+    executor = ExecutorFactory.create_unified_executor(
+        compose_file=compose_file,
+        project_name=project_name,
+        engine=engine,
+    )
+    logger.info(
+        f"UnifiedExecutor created: "
+        f"engine={executor.api.engine_type}, "
+        f"compose_file={compose_file}, "
+        f"project={project_name}"
+    )
+
+    # 2. 初始化服务验证器（传入 executor 以便使用其 API）
+    # Initialize service validator (pass executor to use its API)
+    logger.info("Step 2: Initializing service validator...")
+    init_service_validator(compose_file, executor)
+    logger.info(f"Service validator initialized with compose file: {compose_file}")
+
+    # 3. 初始化并启动 Worker（直接使用 UnifiedExecutor）
+    logger.info("Step 3: Starting task worker...")
+    worker = TaskWorker(executor)
+    worker_instance = worker
+    set_task_worker(worker)
+    await worker.start()
+    logger.info("Task worker started")
+
+    logger.info("=" * 60)
+    logger.info("controllersrv initialization completed")
+    logger.info("=" * 60)
+
+
+async def shutdown_controllersrv():
+    """
+    controllersrv 的关闭回调函数
+    """
+    if worker_instance:
+        logger.info("Shutting down task worker...")
+        await worker_instance.stop()
+        logger.info("Task worker stopped")
+
+
+async def main(host='0.0.0.0', port=22100):
+    """
+    启动 controllersrv 服务
+    
+    Args:
+        host: 监听地址，默认 0.0.0.0（允许容器访问）
+        port: 监听端口，默认 22100
+    """
+    # 1. 初始化路由
+    router_factory = ServerRouter()
+    router_factory.initialize(router_list)
+
+    # 2. 初始化服务器
+    app = AppServer()
+    await app.initialize(
+        service_name="controllersrv",
+        router=router_factory.get_router(),
+        config_dict=service_conf_dict,
+        scheduler_group=None,  # controllersrv 不需要定时任务
+        on_startup=[initialize_controllersrv],
+        on_shutdown=[shutdown_controllersrv],
+    )
+
+    # 3. 启动 Web 服务
+    await app.start(host=host, port=port)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cancan_microstack/cmd/infrasrv/__init__.py

@@ -0,0 +1,5 @@
+"""infrasrv entrypoints.
+
+该模块用于容器内启动 infrasrv 服务。
+Entry points for starting infrasrv inside containers.
+"""