pz-cli 5.0.0__py3-none-any.whl

pz_foundation/configs/default.jsonc

@@ -0,0 +1,452 @@
+{
+  "enabled": true,
+  "database": {
+    "enabled": false,
+    "state": "disabled",
+    "driver": "",
+    "migration_executor": "",
+    "urls": [],
+    "path": "",
+    "host": "localhost",
+    "port": 8570,
+    "user": "",
+    "password": "",
+    "database": "",
+    "min_size": 1,
+    "max_size": 10,
+    "connect_timeout": 5.0,
+    "pool_acquire_timeout": 5.0,
+    "statement_timeout_ms": 30000,
+    "idle_in_transaction_session_timeout_ms": 30000,
+    "pool_max_lifetime": 3600.0,
+    "pool_max_idle": 600.0,
+    "reconnect_timeout": 30.0,
+    "health_check_interval": 60.0,
+    "ssl_mode": "",
+    "ssl_root_cert": "",
+    "ssl_cert": "",
+    "ssl_key": "",
+    "ssl_password": "",
+    "target_session_attrs": ""
+  },
+  "cache": {
+    "enabled": false,
+    "state": "disabled",
+    "backend": "redis",
+    "host": "",
+    "port": 8579,
+    "db": 0,
+    "password": "",
+    "url": "",
+    "service": "mymaster",
+    "allow_cluster": false,
+    "connect_timeout_seconds": 1.0,
+    "socket_timeout_seconds": 1.0,
+    "operation_max_attempts": 2,
+    "connection_retry_attempts": 0,
+    "retry_base_delay_seconds": 0.05,
+    "retry_max_delay_seconds": 0.2,
+    "acquire_failure_cooldown_seconds": 2.0,
+    "health_failure_cooldown_seconds": 2.0
+  },
+  "cache_control": {
+    // 全系统缓存控制策略的唯一通用真相源。
+    // 业务子包只消费 policy id，并在自身写链路声明业务 tags / 失效事实。
+    "runtime_enabled": {
+      // enabled 是 settings center 编译后的显式总开关；null 表示继续按 by_pz_env/default 计算。
+      // 如需临时覆盖，应由 settings center 写入该字段，运行时代码不直接读取 env。
+      "enabled": null,
+      // develop 默认关闭，避免本地开发被旧 HTML、模板上下文或 CMS 读模型缓存干扰。
+      // product 默认开启，保证生产热访问性能。
+      // default 只用于 by_pz_env 未覆盖的环境，保持生产倾向的保守默认。
+      "default": true,
+      "by_pz_env": {
+        "dev": false,
+        "develop": false,
+        "development": false,
+        "local": false,
+        "test": true,
+        "product": true
+      }
+    },
+    "http": {
+      // HTTP 缓存头匹配规则也属于全系统缓存控制，统一集中在这里。
+      // rules 用于极少数路径前缀覆盖 Cache-Control；常规页面和静态资源应优先使用 policies 与 file_extensions。
+      "rules": [],
+      // 这些路径前缀始终输出 no-store；用于 API、登录态入口、dashboard 等不应进入浏览器或 CDN 缓存的区域。
+      "no_store_path_prefixes": [
+        "/api",
+        "/login",
+        "/logout",
+        "/dashboard"
+      ],
+      // 这些路径片段命中时输出 no-store；默认留空，避免用模糊匹配扩大影响面。
+      "no_store_path_tokens": [],
+      // 带这些 query 参数的静态资源视为版本化资源，可使用 http.static.versioned_assets 策略。
+      "versioned_asset_query_keys": [
+        "v",
+        "ver",
+        "version",
+        "hash"
+      ],
+      "file_extensions": {
+        // JS/CSS 文件扩展名，使用 http.static.js_css 策略。
+        "js_css": [
+          ".js",
+          ".css"
+        ],
+        // 图片等普通静态资源扩展名，使用 http.static.assets 策略。
+        "images": [
+          ".ico",
+          ".png",
+          ".jpg",
+          ".jpeg",
+          ".gif",
+          ".webp",
+          ".svg"
+        ],
+        // 字体文件扩展名，使用 http.static.assets 策略。
+        "fonts": [
+          ".woff",
+          ".woff2",
+          ".ttf",
+          ".otf"
+        ],
+        // XML/JSON 等静态数据文件扩展名，使用 http.static.data 策略。
+        "static_data": [
+          ".xml",
+          ".json"
+        ]
+      }
+    },
+    "policies": {
+      // 公开匿名 HTML 的 CDN 缓存头策略；开启时输出 Cloudflare-CDN-Cache-Control: public, max-age=<ttl_seconds>。
+      // 浏览器侧仍保持 Cache-Control: public, max-age=0, must-revalidate；关闭时 Cloudflare 侧明确 no-store。
+      "http.public_html_cdn": {
+        "enabled": true,
+        "ttl_seconds": 3600
+      },
+      // 未带版本参数的 JS/CSS 静态资源缓存 TTL。
+      "http.static.js_css": {
+        "enabled": true,
+        "ttl_seconds": 10800
+      },
+      // 图片、字体等普通静态资源缓存 TTL。
+      "http.static.assets": {
+        "enabled": true,
+        "ttl_seconds": 86400
+      },
+      // XML/JSON 等静态数据资源缓存 TTL。
+      "http.static.data": {
+        "enabled": true,
+        "ttl_seconds": 10800
+      },
+      // 带 v/ver/version/hash 等版本参数的静态资源长期缓存 TTL。
+      "http.static.versioned_assets": {
+        "enabled": true,
+        "ttl_seconds": 31536000
+      },
+      // site_ui 模板上下文、翻译 bundle、SEO nav 等轻量运行期缓存 TTL。
+      "site_ui.template_context": {
+        "enabled": true,
+        "ttl_seconds": 300
+      },
+      // site_ui 通用公开 HTML 响应缓存原语；Blog/CMS/Page Center 只消费，不复制实现。
+      // max_entries 是每个 worker 进程内的最大条目数。
+      // shared_invalidation_versions 开启后，内容 tag 版本会进入 cache key，适配 8-20 worker 场景下的自动失效。
+      "site_ui.public_html_response": {
+        "enabled": true,
+        "ttl_seconds": 60,
+        "max_entries": 512,
+        "shared_invalidation_versions": true
+      },
+      // Blog 是否允许消费通用公开 HTML 响应缓存；TTL/容量仍取 site_ui.public_html_response。
+      "blog.public_html_response": {
+        "enabled": true
+      },
+      // CMS 是否允许消费通用公开 HTML 响应缓存；TTL/容量仍取 site_ui.public_html_response。
+      "cms.public_html_response": {
+        "enabled": true
+      },
+      // CMS app config 读模型缓存 TTL；业务失效事实由 CMS 写链路负责。
+      "cms.app_config": {
+        "enabled": true,
+        "ttl_seconds": 300
+      },
+      // CMS 按公开 path 查询 entry 的读模型缓存 TTL。
+      "cms.entry_by_path": {
+        "enabled": true,
+        "ttl_seconds": 60
+      },
+      // CMS content type 列表缓存 TTL。
+      "cms.content_types": {
+        "enabled": true,
+        "ttl_seconds": 300
+      },
+      // CMS content type SEO 投影缓存 TTL。
+      "cms.content_type_seo": {
+        "enabled": true,
+        "ttl_seconds": 600
+      },
+      // CMS tagcloud 读模型缓存 TTL。
+      "cms.tagcloud": {
+        "enabled": true,
+        "ttl_seconds": 600
+      },
+      // CMS 相关文章读模型缓存 TTL。
+      "cms.related_entries": {
+        "enabled": true,
+        "ttl_seconds": 60
+      },
+      // CMS 热门文章读模型缓存 TTL。
+      "cms.popular_entries": {
+        "enabled": true,
+        "ttl_seconds": 60
+      },
+      // CMS sitemap 生成缓存 TTL。
+      "cms.sitemap": {
+        "enabled": true,
+        "ttl_seconds": 300
+      }
+    }
+  },
+  "health": {
+    "enabled": true,
+    "state": "enabled",
+    "readiness_enabled": true,
+    "runtime_dir": "",
+    "asset_dir": "",
+    "cache_dir": ""
+  },
+  "managed_workers": {
+    // `pz run` 启动宿主时是否先强制收口旧 detached supervisor 与旧 worker，再拉起当前 RuntimePlan 下的 worker。
+    // 默认开启，确保 worker 进程加载最新代码与最新 settings；如需独立运维 worker 生命周期，可在宿主配置中显式改为 false。
+    "force_restart_on_host_start": true,
+    // worker 未声明 replica_count_setting，或 owner app settings 中 count 缺失 / 非正数时使用的全局兜底副本数。
+    "default_replica_count": 1,
+    "crash_loop": {
+      // 单个 worker 在窗口期内连续异常退出达到阈值后，supervisor 停止自动重启并写入 crash_loop_backoff 状态。
+      "max_failures": 5,
+      "failure_window_seconds": 60.0,
+      "base_backoff_seconds": 5.0,
+      "max_backoff_seconds": 300.0
+    }
+  },
+  "mail": {
+    "enabled": false,
+    "state": "disabled",
+    "provider": "smtp",
+    "server": "",
+    "port": 587,
+    "username": "",
+    "password": "",
+    "mail_from": "",
+    "mail_from_name": "",
+    "use_tls": true,
+    "use_ssl": false,
+    "custom_server_url": ""
+  },
+  "observability": {
+    "enabled": true,
+    "state": "enabled",
+    "metrics": {
+      "enabled": false,
+      "path": "/metrics",
+      "namespace": "pz"
+    },
+    "tracing": {
+      "enabled": false,
+      "exporter": ""
+    },
+    "logger": {
+      "bot": {
+        "max_workers": 5,
+        "max_pending": 100
+      },
+      "feishu": {
+        "webhook": "",
+        "secret": "",
+        "webhook_error_event": "",
+        "secret_error_event": "",
+        "webhook_warning_event": "",
+        "secret_warning_event": "",
+        "webhook_custom_event": "",
+        "secret_custom_event": "",
+        "max_text_chars": 12000
+      },
+      "markdown": {
+        "renderer": "bot-markdown-v1"
+      }
+    }
+  },
+  "storage": {
+    "enabled": false,
+    "state": "disabled",
+    "backend": "s3",
+    "subdir": "storage",
+    "base_dir": "",
+    "base_url": "",
+    "bucket": "your-bucket-name",
+    "region_name": "ap-northeast-1",
+    "endpoint_url": "",
+    "access_key_id": "",
+    "secret_access_key": "",
+    "force_path_style": false,
+    "public_base_url": ""
+  },
+  "resources": {
+    // 通用资源编译配置。图片响应式派生属于 foundation resource，而不是某个站点子包。
+    "images": {
+      "enabled": true,
+      // 默认让 `pz resources images` 等价启用 --force，绕过资源构建缓存并覆盖同名派生，避免站点图片变更后继续命中旧产物。
+      // 如需只补缺失派生，可在宿主配置中显式改为 false。
+      "force": true,
+      "min_bytes": 65536,
+      "formats": [
+        "avif",
+        "webp"
+      ],
+      "rules": [],
+      "quality": {
+        "webp": 60,
+        "avif": 45
+      }
+    }
+  },
+  "route_policy": {
+    "default_mode": "public",
+    "auth_paths": [],
+    "public_paths": [],
+    "delegate_paths": []
+  },
+  "middleware": {
+    "enable": {},
+    "geo_country": {
+      "header_priority": [
+        "cf-ipcountry",
+        "cloudfront-viewer-country",
+        "x-country-code",
+        "x-country"
+      ]
+    },
+    "cors": {
+      "allow_origins": [
+        "*"
+      ],
+      "allow_methods": [
+        "*"
+      ],
+      "allow_headers": [
+        "*"
+      ],
+      "expose_headers": [],
+      "max_age": 600
+    },
+    "security_csrf": {
+      "enabled": false,
+      "trusted_origins": [],
+      "safe_methods": [
+        "GET",
+        "HEAD",
+        "OPTIONS"
+      ],
+      "protected_paths": [
+        "/api/"
+      ],
+      "exempt_paths": [],
+      "mode": "protect_list",
+      "cookie": "csrf_token",
+      "header": "X-CSRF-Token"
+    },
+    "compression": {
+      "enabled": true,
+      "minimum_size": 1024,
+      "compresslevel": 6,
+      "skip_content_types": [
+        "image/",
+        "video/",
+        "audio/",
+        "application/zip",
+        "application/gzip",
+        "application/x-gzip",
+        "application/x-7z-compressed",
+        "application/vnd.rar",
+        "application/pdf",
+        "font/woff2"
+      ],
+      "skip_extensions": [
+        ".png",
+        ".jpg",
+        ".jpeg",
+        ".gif",
+        ".webp",
+        ".avif",
+        ".mp4",
+        ".webm",
+        ".mp3",
+        ".ogg",
+        ".wav",
+        ".zip",
+        ".gz",
+        ".br",
+        ".7z",
+        ".rar",
+        ".pdf",
+        ".woff2"
+      ]
+    },
+    "analytics": {
+      "enabled": false,
+      "vendor": "pageview",
+      "sample_rate": 1.0,
+      "google_analytics_id": "",
+      "google_ads_enabled": false,
+      "google_ads_client_id": "",
+      "clarity_key": ""
+    },
+    "security_headers": {
+      "script_src_domains": [],
+      "connect_src_domains": [
+        "http://localhost:8000"
+      ],
+      "img_src_domains": [
+        "http://localhost:8000"
+      ],
+      "frame_src_domains": [],
+      "all_domains": [],
+      "allow_all_https": false,
+      "frame_options": "DENY",
+      "content_type_options": "nosniff",
+      "referrer_policy": "strict-origin-when-cross-origin",
+      "raw_headers": []
+    },
+    "request_logging": {
+      "enabled": true,
+      "json": false,
+      "slow_ms": 1000,
+      "exclude_paths": [
+        "/health",
+        "/live",
+        "/livez",
+        "/liveness",
+        "/ready",
+        "/readiness",
+        "/metrics",
+        "/static/",
+        "/favicon.ico",
+        "/robots.txt",
+        "/docs",
+        "/openapi.json"
+      ],
+      "headers_allowlist": [
+        "user-agent",
+        "accept",
+        "accept-language",
+        "content-type",
+        "referer",
+        "origin",
+        "x-request-id"
+      ]
+    }
+  }
+}

pz_foundation/db/__init__.py

@@ -0,0 +1,94 @@
+"""Foundation database implementations live here."""
+
+from .connection_manager import DBConnectionManager, db_manager
+from .connection_probe import DBConnectionReadinessProbeResult, probe_connection_readiness
+from .config import build_foundation_connections, build_foundation_tortoise_config, get_foundation_tortoise_config
+from .deps import ensure_db, get_db_config, get_read_tx, get_write_tx
+from .lifecycle_status import DBConnectionLifecycleStatus, connection_lifecycle_status
+from .database import (
+    describe_foundation_database_binding,
+    FoundationDatabase,
+    FoundationDatabaseSettings,
+    MySQLFoundationDatabase,
+    normalize_foundation_database_settings,
+    PostgreSQLFoundationDatabase,
+    probe_foundation_database_binding,
+    SQLiteFoundationDatabase,
+    SQLiteFoundationReadinessProbe,
+    SQLiteFoundationSession,
+    SQLiteFoundationTransaction,
+    get_foundation_database,
+    get_foundation_database_if_enabled,
+    load_foundation_database_settings,
+    reset_foundation_databases,
+)
+from .mysql import build_mysql_connections
+from .migrations import FoundationDatabaseMigrationRuntime, build_migration_provider
+from .postgresql import ClusterNode, PostgreSQLClusterManager, build_postgresql_connections, find_cluster_master
+from .session import (
+    DBRequestContext,
+    ReadWriteDBSession,
+    db_session,
+    get_request_context,
+    push_request_context,
+    read_transaction,
+    reset_request_context,
+    run_in_transaction,
+    using_read_db,
+    using_write_db,
+    write_transaction,
+)
+from .sqlite import build_sqlite_connections
+from .tortoise_manager import get_connection_status, tortoise_manager
+
+__all__ = [
+    "ClusterNode",
+    "DBConnectionManager",
+    "DBConnectionLifecycleStatus",
+    "DBConnectionReadinessProbeResult",
+    "DBRequestContext",
+    "describe_foundation_database_binding",
+    "connection_lifecycle_status",
+    "FoundationDatabase",
+    "FoundationDatabaseMigrationRuntime",
+    "FoundationDatabaseSettings",
+    "MySQLFoundationDatabase",
+    "normalize_foundation_database_settings",
+    "PostgreSQLFoundationDatabase",
+    "PostgreSQLClusterManager",
+    "ReadWriteDBSession",
+    "SQLiteFoundationDatabase",
+    "SQLiteFoundationReadinessProbe",
+    "SQLiteFoundationSession",
+    "SQLiteFoundationTransaction",
+    "build_foundation_connections",
+    "build_foundation_tortoise_config",
+    "build_mysql_connections",
+    "build_migration_provider",
+    "build_postgresql_connections",
+    "build_sqlite_connections",
+    "db_session",
+    "db_manager",
+    "find_cluster_master",
+    "get_foundation_database",
+    "get_foundation_database_if_enabled",
+    "get_connection_status",
+    "get_db_config",
+    "get_request_context",
+    "get_read_tx",
+    "get_write_tx",
+    "load_foundation_database_settings",
+    "push_request_context",
+    "read_transaction",
+    "reset_foundation_databases",
+    "reset_request_context",
+    "probe_foundation_database_binding",
+    "probe_connection_readiness",
+    "run_in_transaction",
+    "tortoise_manager",
+    "using_read_db",
+    "using_write_db",
+    "write_transaction",
+    "get_foundation_tortoise_config",
+    "ensure_db",
+]