cancan-microstack 0.0.1__tar.gz

cancan_microstack-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Lai
+
+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.

cancan_microstack-0.0.1/MANIFEST.in

@@ -0,0 +1,9 @@
+global-exclude __pycache__ *.py[cod] *.pyo *.pyd .DS_Store
+prune .pytest_cache
+prune .mypy_cache
+prune .ruff_cache
+prune .venv
+prune build
+prune dist
+exclude .coverage
+exclude coverage.xml

cancan_microstack-0.0.1/PKG-INFO

@@ -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

cancan_microstack-0.0.1/README.md

@@ -0,0 +1,109 @@
+# 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

cancan_microstack-0.0.1/__init__.py

@@ -0,0 +1,14 @@
+"""Cancan Microstack – infrastructure microservice bundle and tooling."""
+from .__version__ import (
+    __author__,
+    __author_email__,
+    __description__,
+    __license__,
+    __title__,
+    __url__,
+    __version__,
+)
+from .core.assets import AssetManager, AssetRecord
+from .core.compose_builder import ComposeBuilder
+from .core.microstack import CancanMicrostack
+from .core.runner import ServiceRunner

cancan_microstack-0.0.1/__version__.py

@@ -0,0 +1,10 @@
+"""Cancan Microstack package metadata."""
+
+__title__ = "cancan-microstack"
+__description__ = "Infrastructure microservice bundle providing controllersrv/infrasrv/opsbffsrv, assets, and orchestration tooling"
+__url__ = "https://github.com/10000ms/cancan_microstack"
+__version__ = "0.0.1"
+__author__ = "Victor Lai"
+__author_email__ = "victor.lai@foxmail.com"
+__license__ = "MIT"
+__copyright__ = "2026 Victor Lai"

cancan_microstack-0.0.1/assets/__init__.py

@@ -0,0 +1,6 @@
+"""Packaged static assets for cancan_microstack.
+
+这些文件会随 cancan_microstack 一起发布，用于导出到业务工作区后再被 Docker/Caddy 等读取。
+These files are shipped with cancan_microstack and can be exported into a workspace,
+so Docker/Caddy can read them via bind mounts.
+"""

cancan_microstack-0.0.1/assets/builds/caddy/Caddyfile

@@ -0,0 +1,187 @@
+# Caddyfile - 反向代理和 Coraza WAF 配置
+# 集成 Coraza WAF 和完整的反向代理功能
+
+{
+    # 全局配置
+    admin 0.0.0.0:2019
+    persist_config off
+    
+    # 访问日志（JSON 格式，包含详细信息）
+    log {
+        output file /var/log/caddy/access.log {
+            roll_size 100mb
+            roll_keep 10
+            roll_keep_for 720h
+        }
+        format json {
+            time_format iso8601
+            message_key msg
+        }
+        level INFO
+    }
+    
+    # 服务器配置
+    servers {
+        metrics
+    }
+    
+    # Coraza WAF 全局配置
+    order coraza_waf first
+}
+
+# HTTP -> HTTPS 重定向（生产环境）
+# :80 {
+#     redir https://{host}{uri} permanent
+# }
+
+# 本地开发 HTTP 端口（8080）
+http://:8080 {
+    # 访问日志
+    log {
+        output file /var/log/caddy/http-access.json {
+            roll_size 50mb
+            roll_keep 10
+        }
+        format json
+    }
+    
+    # 基础健康检查端点
+    handle /health {
+        respond "OK" 200
+    }
+
+    # ===== adminops - 运维管理前端（静态 SPA） =====
+    redir /adminops /adminops/ 308
+    # 资源文件不做 SPA 回退，避免缺失 chunk 被返回 index.html 导致 MIME 错误
+    # Do not apply SPA fallback for assets, otherwise missing chunks return HTML and break module loading
+    handle /adminops/assets/* {
+        root * /srv/www
+        file_server
+    }
+    # 入口 HTML 禁止强缓存，降低发布期间旧 runtime 引用旧 chunk 的概率
+    # Disable strong cache for entry HTML to reduce stale runtime/chunk mismatch after deployments
+    @adminops_index path /adminops /adminops/
+    header @adminops_index Cache-Control "no-store, no-cache, must-revalidate"
+
+    handle_path /adminops/* {
+        root * /srv/www/adminops
+        try_files {path} /index.html
+        file_server
+    }
+    
+    # ===== opsbffsrv - 运营管理服务 =====
+    handle /v1/opsbffsrv/* {
+        reverse_proxy opsbffsrv.service:8080 {
+            lb_policy round_robin
+            header_up X-Real-IP {remote_ip}
+            header_up X-Forwarded-For {remote_ip}
+            header_up X-Forwarded-Proto {scheme}
+            header_up X-Forwarded-Host {host}
+        }
+    }
+
+    # 默认处理（404）
+    handle {
+        respond "Not Found" 404
+    }
+}
+
+# HTTPS 主配置（生产环境，带 WAF）
+:443 {
+    # TLS 配置（自动证书）
+    tls internal {
+        on_demand
+    }
+    
+    # ===== Coraza WAF 配置 =====
+    coraza_waf {
+        # 加载 WAF 配置文件
+        directives `
+            Include /etc/caddy/waf/coraza.conf
+        `
+        
+        # WAF 日志
+        # audit_log /var/log/caddy/waf-audit.log
+    }
+    
+    # 访问日志（详细的 JSON 格式）
+    log {
+        output file /var/log/caddy/access.json {
+            roll_size 50mb
+            roll_keep 20
+        }
+        format json {
+            time_format iso8601
+            message_key message
+            level_key level
+        }
+    }
+    
+    # 基础健康检查端点
+    handle /health {
+        respond "OK" 200
+    }
+
+    # ===== adminops - 运维管理前端（静态 SPA） =====
+    redir /adminops /adminops/ 308
+    # 资源文件不做 SPA 回退，避免缺失 chunk 被返回 index.html 导致 MIME 错误
+    # Do not apply SPA fallback for assets, otherwise missing chunks return HTML and break module loading
+    handle /adminops/assets/* {
+        root * /srv/www
+        file_server
+    }
+    # 入口 HTML 禁止强缓存，降低发布期间旧 runtime 引用旧 chunk 的概率
+    # Disable strong cache for entry HTML to reduce stale runtime/chunk mismatch after deployments
+    @adminops_index path /adminops /adminops/
+    header @adminops_index Cache-Control "no-store, no-cache, must-revalidate"
+
+    handle_path /adminops/* {
+        root * /srv/www/adminops
+        try_files {path} /index.html
+        file_server
+    }
+    
+    # ===== opsbffsrv - 运营管理服务 =====
+    handle /v1/opsbffsrv/* {
+        reverse_proxy opsbffsrv.service:8080 {
+            # 负载均衡
+            lb_policy round_robin
+            
+            # 请求头
+            header_up X-Real-IP {remote_ip}
+            header_up X-Forwarded-For {remote_ip}
+            header_up X-Forwarded-Proto {scheme}
+            header_up X-Forwarded-Host {host}
+        }
+    }
+    
+    # 默认处理（404）
+    handle {
+        respond "Not Found" 404
+    }
+}
+
+# ===== 未来扩展：Coraza WAF 配置示例 =====
+# 注意：需要使用编译了 Coraza 模块的 Caddy 版本
+#
+# :443 {
+#     # Coraza WAF
+#     coraza {
+#         directives `
+#             SecRuleEngine On
+#             SecRequestBodyAccess On
+#             SecResponseBodyAccess Off
+#             SecRequestBodyLimit 13107200
+#             SecRequestBodyNoFilesLimit 131072
+#             
+#             # 加载 OWASP Core Rule Set
+#             Include /etc/coraza/crs-setup.conf
+#             Include /etc/coraza/rules/*.conf
+#             
+#             # 自定义规则
+#             SecRule REQUEST_URI "@contains /admin" \
+#                 "id:1001,phase:1,deny,status:403,msg:'Admin access blocked'"
+#         `
+#     }
+# }
+