cancan-microstack 0.0.1__py3-none-any.whl

cancan_microstack/assets/www/adminops/assets/workflow-CUXs39Ac.js

@@ -0,0 +1 @@
+import{I as t,J as a,K as L,r as c,x as N,E as s}from"./index-CiFlm8oc.js";const $={PENDING:{label:"待调度",color:"var(--text-secondary)",bgColor:"var(--bg-tertiary)",icon:"i-carbon-time"},RUNNING:{label:"运行中",color:"var(--primary-500)",bgColor:"rgba(22, 119, 255, 0.15)",icon:"i-carbon-in-progress"},SUCCESS:{label:"成功",color:"var(--success-500)",bgColor:"rgba(82, 196, 26, 0.15)",icon:"i-carbon-checkmark-filled"},FAILURE:{label:"失败",color:"var(--error-500)",bgColor:"rgba(255, 77, 79, 0.15)",icon:"i-carbon-warning-alt-filled"},CANCELLED:{label:"已取消",color:"var(--warning-600)",bgColor:"rgba(250, 173, 20, 0.2)",icon:"i-carbon-close-outline"},PAUSED:{label:"已暂停",color:"var(--warning-500)",bgColor:"rgba(250, 173, 20, 0.15)",icon:"i-carbon-pause"}},Q={PENDING:{label:"等待中",color:"var(--text-secondary)",bgColor:"var(--bg-tertiary)",icon:"i-carbon-time"},RUNNING:{label:"执行中",color:"var(--primary-500)",bgColor:"rgba(22, 119, 255, 0.15)",icon:"i-carbon-in-progress"},SUSPENDED:{label:"挂起",color:"var(--warning-600)",bgColor:"rgba(250, 173, 20, 0.15)",icon:"i-carbon-pause"},SUCCESS:{label:"成功",color:"var(--success-500)",bgColor:"rgba(82, 196, 26, 0.15)",icon:"i-carbon-checkmark-filled"},FAILURE:{label:"失败",color:"var(--error-500)",bgColor:"rgba(255, 77, 79, 0.15)",icon:"i-carbon-close"},SKIPPED:{label:"跳过",color:"var(--text-tertiary)",bgColor:"var(--bg-secondary)",icon:"i-carbon-skip-forward"},RETRYING:{label:"重试中",color:"var(--primary-600)",bgColor:"rgba(22, 119, 255, 0.2)",icon:"i-carbon-renew"},CANCELLED:{label:"已取消",color:"var(--text-secondary)",bgColor:"rgba(0, 0, 0, 0.05)",icon:"i-carbon-close"}},X={OPEN:{label:"未处理",color:"var(--error-600)",bgColor:"rgba(255, 99, 71, 0.12)",icon:"i-carbon-warning-alt"},ACKED:{label:"已知晓",color:"var(--warning-700)",bgColor:"rgba(250, 173, 20, 0.18)",icon:"i-carbon-reminder"},RESOLVED:{label:"已解决",color:"var(--success-600)",bgColor:"rgba(82, 196, 26, 0.18)",icon:"i-carbon-checkmark"}},Z={CRITICAL:{label:"致命",color:"var(--error-600)",icon:"i-carbon-warning-alt-filled"},MAJOR:{label:"严重",color:"var(--warning-700)",icon:"i-carbon-warning-filled"},MINOR:{label:"提示",color:"var(--primary-600)",icon:"i-carbon-information-filled"}},oo=[{type:"ACTION",label:"HTTP 请求",icon:"i-carbon-api",color:"var(--primary-500)",description:"发送 HTTP 请求",defaultConfig:{async_mode:!1,request:{method:"GET",url:"https://example.com",timeout_seconds:10},context_mappings:{},retry_policy:{enabled:!0,max_attempts:3,interval_seconds:5}}},{type:"TRANSFORM",label:"数据加工",icon:"i-carbon-data-enrichment",color:"var(--success-500)",description:"JSON 数据转换",defaultConfig:{engine:"JINJA2",output_schema:{}}},{type:"LOGIC",label:"条件判断",icon:"i-carbon-direction-fork",color:"var(--warning-500)",description:"If/Else 分支",defaultConfig:{condition:"{{ context.__runtime__.last_output.ok }}"}},{type:"FORK",label:"并行分支",icon:"i-carbon-flow-stream",color:"var(--warning-600)",description:"同时触发多个下游任务",defaultConfig:{branch_node_ids:[],branch_labels:{}}},{type:"LOOP",label:"循环控制",icon:"i-carbon-loop",color:"var(--purple-500)",description:"迭代循环",defaultConfig:{condition:"{{ context.loop_index > 10 or context.__runtime__.last_status != 'SUCCESS' }}",max_iterations:10,loop_next_id:void 0}},{type:"JOIN",label:"汇聚节点",icon:"i-carbon-arrows-vertical",color:"var(--gray-500)",description:"合并分支",defaultConfig:{mode:"ALL",timeout_seconds:3600}}],O=o=>({...o||{},_t:Date.now()}),R=o=>t.Get(a.WORKFLOW_DEFINITIONS,{params:O(o)}),m=o=>t.Get(a.WORKFLOW_DEFINITION_DETAIL(o),{params:{_t:Date.now()}}),S=o=>t.Post(a.WORKFLOW_DEFINITIONS,o),T=(o,n)=>t.Put(a.WORKFLOW_DEFINITION_DETAIL(o),n),y=o=>t.Delete(a.WORKFLOW_DEFINITION_DETAIL(o)),C=o=>t.Post(a.WORKFLOW_DEFINITION_TOGGLE(o)),F=(o,n)=>t.Post(a.WORKFLOW_DEFINITION_DUPLICATE(o),n),k=o=>t.Post(a.WORKFLOW_DEFINITION_PUBLISH(o)),K=o=>t.Post(a.WORKFLOW_DEFINITION_VALIDATE(o)),P=o=>t.Get(a.WORKFLOW_DEFINITION_VERSIONS(o),{params:{_t:Date.now()}}),x=(o,n)=>t.Post(a.WORKFLOW_DEFINITION_ROLLBACK(o),n),G=()=>t.Get(a.WORKFLOW_STATS,{params:{_t:Date.now()}}),eo=o=>t.Get(a.WORKFLOW_RUNS,{params:O(o)}),ro=o=>t.Get(a.WORKFLOW_RUN_GRAPH(o),{params:{_t:Date.now()}}),to=(o,n)=>t.Get(a.WORKFLOW_NODE_LOGS(o,n),{params:{_t:Date.now()}}),ao=(o,n)=>t.Post(a.WORKFLOW_TRIGGER_RUN(o),n),no=o=>t.Get(a.WORKFLOW_ALERTS,{params:O(o)}),io=(o,n)=>t.Post(a.WORKFLOW_ALERT_ACK(o),n),so=(o,n)=>t.Post(a.WORKFLOW_ALERT_RESOLVE(o),n),co=L("workflow",()=>{const o=c([]),n=c(0),g=c(!1),_=c(!1),W=c(null),l=c(null),b=c({nodes:[],edges:[]}),d=c({name:"",description:"",schedule:"0 0 0 * * *",timezone:"Asia/Shanghai",tags:[],is_active:!0,global_context:{}}),v=c({}),p=c(!1),D=c({}),h=N(()=>l.value&&o.value.find(e=>e.id===l.value)||null),I=N(()=>b.value.nodes.length>0),w=e=>{l.value=e},A=e=>{e?(b.value=JSON.parse(JSON.stringify(e.graph_data||{nodes:[],edges:[]})),v.value=JSON.parse(JSON.stringify(e.nodes_config||{})),d.value={name:e.name,description:e.description,schedule:e.schedule,timezone:e.timezone||"Asia/Shanghai",tags:e.tags||[],is_active:e.is_active,global_context:e.global_context||{}}):(b.value={nodes:[],edges:[]},v.value={},d.value={name:"",description:"",schedule:"0 0 0 * * *",timezone:"Asia/Shanghai",tags:[],is_active:!0,global_context:{}}),p.value=!1},f=async e=>{g.value=!0;try{const r=await R(e);return o.value=r?.list||[],n.value=r?.total||0,!l.value&&o.value.length>0&&(l.value=o.value[0].id),r}catch(r){throw s.error("获取编排列表失败"),r}finally{g.value=!1}},E=async e=>{const r=await m(e),i=o.value.findIndex(u=>u.id===e);return i>=0?o.value[i]=r:o.value.unshift(r),l.value=e,r};return{definitions:o,total:n,loading:g,stats:W,statsLoading:_,selectedId:l,designerGraph:b,designerMeta:d,designerNodesConfig:v,designerDirty:p,versionHistories:D,currentDefinition:h,hasGraphDraft:I,setSelectedId:w,resetDesigner:A,fetchDefinitionsAction:f,fetchDefinitionDetailAction:E,saveDefinition:async(e,r)=>{try{const i=r?await T(r,e):await S(e);return s.success("工作流保存成功"),await f(),i}catch(i){throw s.error("保存失败"),i}},removeDefinition:async e=>{await y(e),o.value=o.value.filter(r=>r.id!==e),l.value===e&&(l.value=o.value[0]?.id||null),s.success("已删除")},toggleDefinitionStatus:async e=>{const r=await C(e),i=o.value.findIndex(u=>u.id===e);return i>=0&&(o.value[i]=r),s.success(r.is_active?"已启用":"已停用"),r},duplicateDefinitionAction:async(e,r)=>{const u=await F(e,{source_workflow_id:e,name:r});return o.value.unshift(u),s.success("复制成功"),u},fetchWorkflowStatsAction:async()=>{_.value=!0;try{const e=await G();return W.value=e,e}catch{return null}finally{_.value=!1}},validateCurrentDesigner:async e=>{try{const r=await K(e);return r.valid?s.success("校验通过"):s.warning(`校验未通过：${(r.issues||[]).join("；")}`),r}catch(r){throw s.error("校验失败"),r}},publishDefinition:async e=>{try{const r=await k(e);return s.success("已发布最新版本"),await f(),r}catch(r){throw s.error("发布失败"),r}},fetchWorkflowVersionsAction:async e=>{const r=await P(e);return D.value[e]=r.versions||[],r},rollbackWorkflowVersionAction:async(e,r)=>{const i=await x(e,r);return s.success("已回滚到指定版本"),await Promise.all([E(e),f()]),i}}});export{oo as D,Q as N,$ as W,X as a,Z as b,io as c,to as d,ro as e,no as f,eo as g,so as r,ao as t,co as u};

cancan_microstack/assets/www/adminops/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/adminops/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <meta name="theme-color" content="#ffffff" />
+    <meta name="description" content="现代化 OPS 运维管理平台" />
+    <title>OPS 管理平台</title>
+    <script type="module" crossorigin src="/adminops/assets/index-CiFlm8oc.js"></script>
+    <link rel="stylesheet" crossorigin href="/adminops/assets/index-UW0T1Dkc.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

cancan_microstack/assets/www/adminops/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

cancan_microstack/cli/__init__.py

@@ -0,0 +1,14 @@
+"""Command line interface helpers for Cancan Microstack."""
+from datetime import datetime
+from typing import Any
+
+
+def log(message: str, **fields: Any) -> None:
+    """Lightweight structured logger for CLI feedback."""
+
+    prefix = datetime.now().isoformat(timespec="seconds")
+    extras = " ".join(f"{key}={value}" for key, value in fields.items() if value is not None)
+    print(f"[{prefix}] {message} {extras}".strip())
+
+
+from .main import main  # noqa: E402  (import after helper definition)

cancan_microstack/cli/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point so `python -m cancan_microstack.cli` works.
+
+提供 `python -m cancan_microstack.cli` 入口，方便与文档一致。
+"""
+from .main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cancan_microstack/cli/main.py

@@ -0,0 +1,552 @@
+"""Argparse-based CLI for Cancan Microstack."""
+import argparse
+import os
+import time
+from pathlib import Path
+from typing import Sequence
+
+from .. import __version__
+from ..core.stack_manager import StackManager
+from ..core.stack_manager import StackOptions
+from ..core.microstack import CancanMicrostack
+from . import log
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cancan", description="Cancan Microstack helper commands")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    assets_parser = sub.add_parser("assets", help="Inspect packaged assets")
+    assets_sub = assets_parser.add_subparsers(dest="assets_command", required=True)
+
+    list_parser = assets_sub.add_parser("list", help="List assets")
+    list_parser.add_argument("subdir", nargs="?", help="Optional asset subdirectory filter")
+
+    export_parser = assets_sub.add_parser("export", help="Export asset to destination")
+    export_parser.add_argument("logical_name", help="Asset logical name, e.g. docker/docker-compose.infra.yml")
+    export_parser.add_argument("destination", help="Destination file or directory path")
+    export_parser.add_argument("--overwrite", action="store_true", help="Overwrite destination when it exists")
+
+    compose_parser = sub.add_parser("compose", help="Compose orchestration helpers")
+    compose_sub = compose_parser.add_subparsers(dest="compose_command", required=True)
+    build_parser = compose_sub.add_parser("build", help="Generate merged compose stack")
+    build_parser.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+    build_parser.add_argument("--service-file", help="Optional service compose file from workspace")
+    build_parser.add_argument("--override", action="append", default=[], help="Additional override compose files")
+    build_parser.add_argument("--output", help="Target compose file path (default: compose.cancan.yml)")
+    build_parser.add_argument(
+        "--bootstrap",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Export missing workspace assets (infra compose, Caddy/service Dockerfiles, DDL)",
+    )
+
+    svc_parser = sub.add_parser("services", help="Run bundled services")
+    svc_sub = svc_parser.add_subparsers(dest="services_command", required=True)
+    run_parser = svc_sub.add_parser("run", help="Run a managed service")
+    run_parser.add_argument("name", choices=["controllersrv", "infrasrv", "opsbffsrv"], help="Service name")
+    run_parser.add_argument("--host", default="0.0.0.0", help="Host binding")
+    run_parser.add_argument("--port", type=int, help="Port binding (defaults depend on service)")
+    run_parser.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+
+    sub.add_parser("version", help="Show version")
+
+    doctor_parser = sub.add_parser("doctor", help="Diagnose environment & config readiness before stack up")
+    doctor_parser.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+
+    init_parser = sub.add_parser("init", help="Scaffold a minimal runnable workspace (compose sample + .env + overrides)")
+    init_parser.add_argument("--workspace", default=".", help="Target workspace dir (default: current directory)")
+
+    stack_parser = sub.add_parser("stack", help="Start/stop the whole microstack")
+    stack_sub = stack_parser.add_subparsers(dest="stack_command", required=True)
+
+    stack_up = stack_sub.add_parser("up", help="Build + bootstrap + start controllersrv + compose up")
+    stack_up.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+    stack_up.add_argument("--service-file", default="docker-compose.services.yml", help="Business compose file")
+    stack_up.add_argument("--override", action="append", default=[], help="Additional override compose files")
+    stack_up.add_argument("--output", help="Target compose file path (default: compose.cancan.yml)")
+    stack_up.add_argument(
+        "--bootstrap",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Export missing workspace assets (infra compose, Caddy/service Dockerfiles, DDL, adminops)",
+    )
+    stack_up.add_argument(
+        "--with-controllersrv",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Start/ensure host controllersrv is running before bringing up containers",
+    )
+    stack_up.add_argument("--controllersrv-host", default="127.0.0.1", help="controllersrv bind host")
+    stack_up.add_argument("--controllersrv-port", default=22100, type=int, help="controllersrv bind port")
+    stack_up.add_argument(
+        "--engine",
+        choices=["auto", "docker", "podman"],
+        default="auto",
+        help="Container engine for compose command detection",
+    )
+    stack_up.add_argument(
+        "--build",
+        action="store_true",
+        help="Force rebuild images (equivalent to compose up --build)",
+    )
+
+    stack_down = stack_sub.add_parser("down", help="Compose down + stop controllersrv")
+    stack_down.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+    stack_down.add_argument("--compose-file", default="compose.cancan.yml", help="Compose file to use")
+    stack_down.add_argument(
+        "--with-controllersrv",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Stop host controllersrv after bringing down containers",
+    )
+    stack_down.add_argument(
+        "--volumes",
+        action="store_true",
+        help="Remove named volumes when bringing stack down",
+    )
+    stack_down.add_argument(
+        "--engine",
+        choices=["auto", "docker", "podman"],
+        default="auto",
+        help="Container engine for compose command detection",
+    )
+
+    stack_status = stack_sub.add_parser("status", help="Show stack status (controllersrv + compose ps)")
+    stack_status.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+    stack_status.add_argument("--compose-file", default="compose.cancan.yml", help="Compose file to use")
+    stack_status.add_argument(
+        "--engine",
+        choices=["auto", "docker", "podman"],
+        default="auto",
+        help="Container engine for compose command detection",
+    )
+
+    controllersrv_parser = sub.add_parser("controllersrv", help="Manage host controllersrv daemon")
+    controllersrv_sub = controllersrv_parser.add_subparsers(dest="controllersrv_command", required=True)
+
+    controllersrv_restart = controllersrv_sub.add_parser(
+        "restart",
+        help="Stop existing daemon (if any) and start a fresh controllersrv on the host",
+    )
+    controllersrv_restart.add_argument("--workspace", default=".", help="Workspace root (default: current directory)")
+    controllersrv_restart.add_argument("--host", default="127.0.0.1", help="controllersrv bind host")
+    controllersrv_restart.add_argument("--port", type=int, default=22100, help="controllersrv bind port")
+    controllersrv_restart.add_argument(
+        "--engine",
+        choices=["auto", "docker", "podman"],
+        default="auto",
+        help="Container engine preference propagated into controllersrv (auto = detect)",
+    )
+    controllersrv_restart.add_argument(
+        "--wait",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Wait for /internal/health after restart (default: enabled)",
+    )
+    controllersrv_restart.add_argument(
+        "--timeout",
+        type=float,
+        default=8.0,
+        help="Seconds to wait for controllersrv health before reporting timeout",
+    )
+
+    return parser
+
+
+def _write_text_if_missing(path: Path, content: str) -> None:
+    """仅在文件不存在时写入内容。
+    Write content only when the file does not exist.
+    """
+
+    if path.exists():
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _seed_env_file(workspace: Path, stack: CancanMicrostack) -> None:
+    """缺失时从模板生成工作区 .env，并填入新鲜的 AUTH_TOTP_FERNET_KEY。
+    Create workspace .env from the template (when missing) with a fresh TOTP encryption key.
+
+    说明 / Note: opsbffsrv 生产模式下要求 AUTH_TOTP_FERNET_KEY 非空，否则拒绝启动；
+    这里为每个工作区生成一个稳定的真实 key，既保证开箱即用，又避免共享弱默认。
+    opsbffsrv refuses to start in prod mode with an empty key; we generate a real,
+    per-workspace key so the stack works out of the box without a shared weak default.
+    """
+
+    env_path = workspace / ".env"
+    if env_path.exists():
+        return
+    try:
+        template = stack.assets.read_text("env/.env.example")
+    except Exception:
+        return
+
+    key = ""
+    try:
+        from cryptography.fernet import Fernet
+        key = Fernet.generate_key().decode()
+    except Exception:
+        key = ""
+
+    lines = []
+    for line in template.splitlines():
+        if key and line.startswith("AUTH_TOTP_FERNET_KEY="):
+            lines.append(f"AUTH_TOTP_FERNET_KEY={key}")
+        else:
+            lines.append(line)
+    env_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _bootstrap_workspace_files(workspace: Path, stack: CancanMicrostack) -> None:
+    """为 compose 运行准备工作区文件（缺失则创建）。
+    Bootstrap workspace files needed to run compose (create when missing).
+
+    目标 / Goals:
+    - 在缺失时导出运行时资产到工作区：infra compose、Caddy/Service Dockerfile、DDL、adminops 前端。
+      Export runtime assets into the workspace when missing: infra compose,
+      Caddy/service Dockerfiles, DDL, and the adminops frontend.
+
+    说明 / Note: 容器内服务直接以 ``python -m cancan_microstack.cmd.<svc>.run`` 运行**已安装的包**，
+    不再需要工作区里的 ``cmd/*`` 包装脚本（旧布局遗留，已移除）。
+    Containerized services run the installed package directly via
+    ``python -m cancan_microstack.cmd.<svc>.run``; no workspace ``cmd/*`` wrappers are needed.
+    """
+
+    def _export_asset_if_missing(logical_name: str, destination: Path) -> None:
+        """Export packaged assets on demand without overwriting user changes.
+
+        按需导出打包资产，避免覆盖用户在工作区中的自定义内容。
+        """
+
+        if destination.exists():
+            return
+        try:
+            stack.export_asset(logical_name, destination, overwrite=False)
+        except FileExistsError:
+            pass
+
+    # Optional export: infra compose file for include-based docker-compose.yml.
+    # 可选导出：用于 include 的 infra compose 文件（缺失才导出）。
+    target_infra_file = workspace / "infra" / "docker-compose.infra.yml"
+    _export_asset_if_missing("docker/docker-compose.infra.yml", target_infra_file)
+
+    # Export base Dockerfile scaffolds for caddy + python services when missing.
+    # 导出 Caddy 与 Python 服务镜像的基础脚手架（缺失时才复制）。
+    _export_asset_if_missing("builds/caddy", workspace / "builds" / "caddy")
+    _export_asset_if_missing("builds/service", workspace / "builds" / "service")
+
+    # Ensure Postgres init scripts exist so compose can create logical databases on first boot.
+    # 确保 PostgreSQL 初始化脚本存在，便于首次启动时创建 infra/ops/biz 数据库。
+    _export_asset_if_missing("ddl/create_db.sql", workspace / "ddl" / "create_db.sql")
+
+    # Export the env template and seed a workspace .env (with a fresh TOTP key) when missing.
+    # 导出 env 模板；缺失时生成带新鲜 TOTP 密钥的工作区 .env（供 compose 注入凭据/密钥）。
+    _export_asset_if_missing("env/.env.example", workspace / ".env.example")
+    _seed_env_file(workspace, stack)
+
+    # Export adminops frontend into workspace for Caddy to serve.
+    # 导出 adminops 前端到工作区，供 Caddy 静态挂载使用。
+    target_adminops_dir = workspace / "builds" / "caddy" / "www" / "adminops"
+    should_export_adminops = (not target_adminops_dir.exists())
+    if target_adminops_dir.exists() and target_adminops_dir.is_dir():
+        try:
+            should_export_adminops = not any(target_adminops_dir.iterdir())
+        except OSError:
+            should_export_adminops = True
+
+    if should_export_adminops:
+        try:
+            stack.export_asset("www/adminops", target_adminops_dir, overwrite=False)
+        except FileExistsError:
+            # Race: another process created it.
+            # 竞态条件：目录被并发创建，忽略即可。
+            pass
+
+
+_SERVICES_COMPOSE_SAMPLE = """\
+# 你的业务服务；`cancan compose build` 会把它与内置基础设施 compose 合并。
+# Your business services. Merged with the bundled infra compose by `cancan compose build`.
+services:
+  # 示例服务 —— 替换为你自己的。Example service — replace with your own.
+  app.service:
+    # build: ./app          # 你的业务镜像 / your business image
+    image: app_python_service:latest
+    networks: [app_network]
+    expose: ["8000"]
+    # depends_on / environment / volumes ... 按需添加 / add as needed
+"""
+
+_OVERRIDES_README = """\
+# cancan_overrides
+
+在这里放你要替换的 cancan 内置服务文件（免 fork）。运行时会优先加载本目录。
+Drop files here to override cancan's bundled services without forking; loaded with priority at runtime.
+
+例 / Example:
+    cancan_overrides/infrasrv/conf/config.py   # 只放你要改的文件 / only the files you change
+
+也可用环境变量 CANCAN_OVERRIDE_ROOT 指定其它目录。
+You can also point CANCAN_OVERRIDE_ROOT at a different directory.
+"""
+
+_WS_GITIGNORE = """\
+.env
+server_log_data/
+compose.cancan.yml
+builds/caddy/logs/
+"""
+
+_WS_README = """\
+# Cancan workspace
+
+```bash
+cancan doctor        # 预检环境 / pre-flight checks
+cancan stack up      # 启动整套栈 / bring the stack up
+cancan stack status
+cancan stack down
+```
+
+- 业务服务写在 `docker-compose.services.yml`。Business services live in `docker-compose.services.yml`.
+- 配置与密钥在 `.env`（已自动生成 TOTP 加密 key；生产请修改弱默认值）。
+  Config & secrets in `.env` (a TOTP key is generated for you; change weak defaults before production).
+- 用 `cancan_overrides/<service>/` 免 fork 覆盖内置服务。Override bundled services via `cancan_overrides/<service>/`.
+"""
+
+
+def _scaffold_workspace(workspace: Path, stack: CancanMicrostack) -> None:
+    """生成一个最小可跑的工作区 / Scaffold a minimal runnable workspace."""
+
+    workspace.mkdir(parents=True, exist_ok=True)
+    # 复用同一套资产 bootstrap（infra compose / Caddy·service Dockerfile / ddl / adminops / .env）。
+    # Reuse the same asset bootstrap.
+    _bootstrap_workspace_files(workspace, stack)
+    # 仅 scaffold 才生成的文件 / scaffold-only files.
+    _write_text_if_missing(workspace / "docker-compose.services.yml", _SERVICES_COMPOSE_SAMPLE)
+    _write_text_if_missing(workspace / "cancan_overrides" / "README.md", _OVERRIDES_README)
+    _write_text_if_missing(workspace / ".gitignore", _WS_GITIGNORE)
+    _write_text_if_missing(workspace / "README.md", _WS_README)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    # The service container image installs `cancan-microstack==${CANCAN_VERSION}`,
+    # so expose the package version to every compose subprocess. setdefault keeps
+    # an explicit user override (e.g. building a different/dev version) intact.
+    os.environ.setdefault("CANCAN_VERSION", __version__)
+
+    stack = CancanMicrostack()
+    stack_manager = StackManager(stack)
+
+    if args.command == "assets":
+        if args.assets_command == "list":
+            records = stack.assets.list_assets(args.subdir)
+            for record in records:
+                log("asset", name=record.logical_name, path=record.path, is_dir=record.is_dir)
+            return 0
+        if args.assets_command == "export":
+            destination = Path(args.destination).expanduser().resolve()
+            stack.export_asset(args.logical_name, destination, overwrite=args.overwrite)
+            return 0
+
+    if args.command == "compose" and args.compose_command == "build":
+        workspace = Path(args.workspace).expanduser().resolve()
+        service_file = Path(args.service_file).resolve() if args.service_file else None
+        overrides = [Path(item).expanduser().resolve() for item in args.override]
+        output = Path(args.output).expanduser().resolve() if args.output else None
+        if args.bootstrap:
+            _bootstrap_workspace_files(workspace, stack)
+        stack.build_compose(workspace=workspace, service_file=service_file, overrides=overrides, output=output)
+        log("compose written", path=output or workspace / "compose.cancan.yml")
+        return 0
+
+    if args.command == "stack":
+        if args.stack_command == "up":
+            workspace = Path(args.workspace).expanduser().resolve()
+            service_file = Path(args.service_file).expanduser().resolve() if args.service_file else None
+            overrides = [Path(item).expanduser().resolve() for item in args.override]
+            output = Path(args.output).expanduser().resolve() if args.output else None
+
+            if args.bootstrap:
+                _bootstrap_workspace_files(workspace, stack)
+
+            start_time = time.perf_counter()
+
+            def _step(msg: str) -> float:
+                now = time.perf_counter()
+                elapsed = now - start_time
+                print(f"[stack] +{elapsed:0.2f}s {msg}")
+                return now
+
+            _step(f"workspace={workspace}")
+
+            options = StackOptions(
+                workspace=workspace,
+                service_file=service_file,
+                overrides=overrides,
+                output=output,
+                bootstrap=args.bootstrap,
+                engine=(None if args.engine == "auto" else args.engine),
+                controllersrv_host=args.controllersrv_host,
+                controllersrv_port=args.controllersrv_port,
+                with_controllersrv=args.with_controllersrv,
+            )
+
+            compose_file = stack_manager.build(options)
+            if options.with_controllersrv:
+                _step(f"start controllersrv (engine={options.engine or 'auto'})")
+                pid = stack_manager.start_controllersrv(options)
+                log("controllersrv", status="running", pid=pid, host=options.controllersrv_host,
+                    port=options.controllersrv_port)
+                paths = stack_manager.get_controllersrv_daemon_paths(workspace)
+                print(f"[stack] controllersrv pid={pid} log={paths.log_file} pidfile={paths.pid_file}")
+
+                _step("wait controllersrv /internal/health")
+                ready = stack_manager.wait_controllersrv_ready(
+                    host=options.controllersrv_host,
+                    port=options.controllersrv_port,
+                    timeout_seconds=8.0,
+                )
+                if not ready:
+                    print(
+                        "[stack] WARNING: controllersrv health not ready yet. "
+                        "If startup is slow, check its log: "
+                        f"{paths.log_file}"
+                    )
+
+            _step(f"compose up -d{' --build' if args.build else ''} (engine={options.engine or 'auto'})")
+            print(f"[stack] compose logs -> {workspace / 'server_log_data' / 'stack' / 'compose.up.log'}")
+            stack_manager.compose_up(
+                workspace=workspace,
+                compose_file=compose_file,
+                engine=options.engine,
+                build=args.build,
+            )
+            _step("done")
+            log("stack", status="up", compose_file=compose_file)
+            return 0
+
+        if args.stack_command == "down":
+            workspace = Path(args.workspace).expanduser().resolve()
+            compose_file = Path(args.compose_file).expanduser().resolve()
+            engine = None if args.engine == "auto" else args.engine
+
+            stack_manager.compose_down(
+                workspace=workspace,
+                compose_file=compose_file,
+                engine=engine,
+                remove_volumes=args.volumes,
+            )
+            if args.with_controllersrv:
+                stopped = stack_manager.stop_controllersrv(workspace)
+                log("controllersrv", status=("stopped" if stopped else "not_running"))
+            log("stack", status="down")
+            return 0
+
+        if args.stack_command == "status":
+            workspace = Path(args.workspace).expanduser().resolve()
+            compose_file = Path(args.compose_file).expanduser().resolve()
+            engine = None if args.engine == "auto" else args.engine
+
+            # controllersrv status via pidfile
+            from ..runtime.host_daemon import default_daemon_paths
+            from ..runtime.host_daemon import read_pid
+
+            paths = default_daemon_paths(workspace, name="controllersrv")
+            pid = read_pid(paths.pid_file)
+            log("controllersrv", pid=pid, pid_file=str(paths.pid_file))
+            stack_manager.compose_ps(workspace=workspace, compose_file=compose_file, engine=engine)
+            return 0
+
+    if args.command == "controllersrv":
+        workspace = Path(args.workspace).expanduser().resolve()
+        engine = None if args.engine == "auto" else args.engine
+        options = StackOptions(
+            workspace=workspace,
+            service_file=None,
+            overrides=[],
+            output=None,
+            bootstrap=False,
+            engine=engine,
+            controllersrv_host=args.host,
+            controllersrv_port=args.port,
+            with_controllersrv=True,
+        )
+
+        if args.controllersrv_command == "restart":
+            stopped = stack_manager.stop_controllersrv(workspace)
+            log(
+                "controllersrv",
+                action="stop",
+                status=("stopped" if stopped else "not_running"),
+                workspace=str(workspace),
+            )
+            pid = stack_manager.start_controllersrv(options)
+            log(
+                "controllersrv",
+                action="start",
+                status="running",
+                pid=pid,
+                host=options.controllersrv_host,
+                port=options.controllersrv_port,
+                engine=options.engine or "auto",
+            )
+            if args.wait:
+                ready = stack_manager.wait_controllersrv_ready(
+                    host=options.controllersrv_host,
+                    port=options.controllersrv_port,
+                    timeout_seconds=args.timeout,
+                )
+                log(
+                    "controllersrv",
+                    action="wait_health",
+                    status=("ready" if ready else "timeout"),
+                    timeout=args.timeout,
+                )
+                if not ready:
+                    print(
+                        "[controllersrv] WARNING: health check timeout; "
+                        "inspect daemon logs if startup takes longer than expected."
+                    )
+            return 0
+
+    if args.command == "services" and args.services_command == "run":
+        workspace = Path(args.workspace).expanduser().resolve()
+        default_ports = {
+            "controllersrv": 22100,
+            "infrasrv": 8080,
+            "opsbffsrv": 8080,
+        }
+        stack.run_service(
+            args.name,
+            host=args.host,
+            port=(args.port if args.port is not None else default_ports[args.name]),
+            workspace=workspace,
+        )
+        return 0
+
+    if args.command == "version":
+        print(__version__)
+        return 0
+
+    if args.command == "doctor":
+        from ..core.doctor import run_doctor
+
+        workspace = Path(args.workspace).expanduser().resolve()
+        return run_doctor(workspace)
+
+    if args.command == "init":
+        workspace = Path(args.workspace).expanduser().resolve()
+        _scaffold_workspace(workspace, stack)
+        log("init", workspace=str(workspace), status="ready", next="cancan doctor && cancan stack up")
+        return 0
+
+    parser.error("Unsupported command")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())