Merged
chore(registry): 同步特性分支的注册中心代码到develop分支 #375
dingyichen1Add on 18 days ago
chore(registry): 同步特性分支的注册中心代码到develop分支 #375
Merged
Total: 82 files changed+13349-240
| @@ -386,49 +386,49 @@ def format_report_markdown(analysis: Dict[str, Any]) -> str: | |||
| 386 | 386 | ||
| 387 | # Error Type Explanation | 387 | # Error Type Explanation |
| 388 | lines.append("## Error Categories\n") | 388 | lines.append("## Error Categories\n") |
| 389 | - lines.append("- **Category A (Navigation Failure)**: 没有进入正确分类") | 389 | + lines.append("- **Category A (Navigation Failure)**: did not enter the correct category") |
| 390 | - lines.append("- **Category B (Selection Failure)**: 进入正确分类但没有选择正确工具") | 390 | + lines.append("- **Category B (Selection Failure)**: entered the correct category but did not select the correct tool") |
| 391 | lines.append("") | 391 | lines.append("") |
| 392 | 392 | ||
| 393 | # Category A Errors - Detailed | 393 | # Category A Errors - Detailed |
| 394 | cat_a_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'A_navigation_failure'] | 394 | cat_a_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'A_navigation_failure'] |
| 395 | if cat_a_errors: | 395 | if cat_a_errors: |
| 396 | lines.append("---") | 396 | lines.append("---") |
| 397 | - lines.append("# Category A: 没有进入正确分类\n") | 397 | + lines.append("# Category A: did not enter the correct category\n") |
| 398 | for i, error in enumerate(cat_a_errors): | 398 | for i, error in enumerate(cat_a_errors): |
| 399 | lines.append(f"## {i+1}. {error['query_id']}\n") | 399 | lines.append(f"## {i+1}. {error['query_id']}\n") |
| 400 | - lines.append(f"**请求内容**: {error['query']}\n") | 400 | + lines.append(f"**Query**: {error['query']}\n") |
| 401 | 401 | ||
| 402 | - # 正确工具 | 402 | + # correct tools |
| 403 | for tool in error['correct_tools_detail']: | 403 | for tool in error['correct_tools_detail']: |
| 404 | if not tool['was_found']: | 404 | if not tool['was_found']: |
| 405 | - lines.append("**正确工具**:") | 405 | + lines.append("**Correct tool**:") |
| 406 | lines.append(f"- ID: `{tool['tool_id']}`") | 406 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 407 | - lines.append(f"- 名称: {tool['tool_name']}") | 407 | + lines.append(f"- Name: {tool['tool_name']}") |
| 408 | - lines.append(f"- 描述: {tool['tool_description']}") | 408 | + lines.append(f"- Description: {tool['tool_description']}") |
| 409 | lines.append("") | 409 | lines.append("") |
| 410 | 410 | ||
| 411 | - # 正确工具分类:完整链条+描述 | 411 | + # correct tool categories: full chain + description |
| 412 | if tool.get('category_paths'): | 412 | if tool.get('category_paths'): |
| 413 | - lines.append("**正确工具分类**:") | 413 | + lines.append("**Correct tool category**:") |
| 414 | for cat_path in tool['category_paths']: | 414 | for cat_path in tool['category_paths']: |
| 415 | - lines.append(f"- 路径: {cat_path['path_str']}") | 415 | + lines.append(f"- Path: {cat_path['path_str']}") |
| 416 | - lines.append(f"- 描述: {cat_path['description'][:300]}...") | 416 | + lines.append(f"- Description: {cat_path['description'][:300]}...") |
| 417 | lines.append("") | 417 | lines.append("") |
| 418 | 418 | ||
| 419 | - # 进入的错误工具分类:完整链条+描述 | 419 | + # wrongly entered tool categories: full chain + description |
| 420 | if error.get('visited_category_paths'): | 420 | if error.get('visited_category_paths'): |
| 421 | - lines.append("**进入的错误分类**:") | 421 | + lines.append("**Wrongly entered category**:") |
| 422 | - # 去重,只显示唯一的分类路径 | 422 | + # deduplicate, show only unique category paths |
| 423 | seen_cats = set() | 423 | seen_cats = set() |
| 424 | for cat_path in error['visited_category_paths']: | 424 | for cat_path in error['visited_category_paths']: |
| 425 | if cat_path['cat_id'] not in seen_cats: | 425 | if cat_path['cat_id'] not in seen_cats: |
| 426 | seen_cats.add(cat_path['cat_id']) | 426 | seen_cats.add(cat_path['cat_id']) |
| 427 | - lines.append(f"- 路径: {cat_path['path_str']}") | 427 | + lines.append(f"- Path: {cat_path['path_str']}") |
| 428 | - lines.append(f"- 描述: {cat_path['description']}") | 428 | + lines.append(f"- Description: {cat_path['description']}") |
| 429 | lines.append("") | 429 | lines.append("") |
| 430 | else: | 430 | else: |
| 431 | - lines.append("**进入的错误分类**: 无\n") | 431 | + lines.append("**Wrongly entered category**: none\n") |
| 432 | 432 | ||
| 433 | lines.append("---\n") | 433 | lines.append("---\n") |
| 434 | 434 | ||
| @@ -436,45 +436,45 @@ def format_report_markdown(analysis: Dict[str, Any]) -> str: | |||
| 436 | cat_b_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'B_selection_failure'] | 436 | cat_b_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'B_selection_failure'] |
| 437 | if cat_b_errors: | 437 | if cat_b_errors: |
| 438 | lines.append("---") | 438 | lines.append("---") |
| 439 | - lines.append("# Category B: 进入正确分类但没有选择正确工具\n") | 439 | + lines.append("# Category B: entered the correct category but did not select the correct tool\n") |
| 440 | for i, error in enumerate(cat_b_errors): | 440 | for i, error in enumerate(cat_b_errors): |
| 441 | lines.append(f"## {i+1}. {error['query_id']}\n") | 441 | lines.append(f"## {i+1}. {error['query_id']}\n") |
| 442 | - lines.append(f"**请求内容**: {error['query']}\n") | 442 | + lines.append(f"**Query**: {error['query']}\n") |
| 443 | - lines.append(f"**访问过的分类**: {error['visited_categories']}\n") | 443 | + lines.append(f"**Visited categories**: {error['visited_categories']}\n") |
| 444 | 444 | ||
| 445 | - # 正确工具 | 445 | + # correct tools |
| 446 | for tool in error['correct_tools_detail']: | 446 | for tool in error['correct_tools_detail']: |
| 447 | if not tool['was_found']: | 447 | if not tool['was_found']: |
| 448 | - lines.append("**正确工具**:") | 448 | + lines.append("**Correct tool**:") |
| 449 | lines.append(f"- ID: `{tool['tool_id']}`") | 449 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 450 | - lines.append(f"- 名称: {tool['tool_name']}") | 450 | + lines.append(f"- Name: {tool['tool_name']}") |
| 451 | - lines.append(f"- 描述: {tool['tool_description']}") | 451 | + lines.append(f"- Description: {tool['tool_description']}") |
| 452 | lines.append("") | 452 | lines.append("") |
| 453 | 453 | ||
| 454 | - # 正确工具分类 | 454 | + # correct tool category |
| 455 | if tool['categories']: | 455 | if tool['categories']: |
| 456 | - lines.append("**正确工具分类**:") | 456 | + lines.append("**Correct tool category**:") |
| 457 | for cat in tool['categories']: | 457 | for cat in tool['categories']: |
| 458 | lines.append(f"- ID: `{cat['id']}`") | 458 | lines.append(f"- ID: `{cat['id']}`") |
| 459 | - lines.append(f"- 名称: {cat['name']}") | 459 | + lines.append(f"- Name: {cat['name']}") |
| 460 | - lines.append(f"- 描述: {cat['description'][:300]}...") | 460 | + lines.append(f"- Description: {cat['description'][:300]}...") |
| 461 | lines.append("") | 461 | lines.append("") |
| 462 | 462 | ||
| 463 | - # 错误工具 | 463 | + # wrong tools |
| 464 | if error['wrong_tools_detail']: | 464 | if error['wrong_tools_detail']: |
| 465 | - lines.append("**错误工具**:") | 465 | + lines.append("**Wrong tool**:") |
| 466 | for tool in error['wrong_tools_detail'][:3]: | 466 | for tool in error['wrong_tools_detail'][:3]: |
| 467 | lines.append(f"- ID: `{tool['tool_id']}`") | 467 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 468 | - lines.append(f"- 名称: {tool['tool_name']}") | 468 | + lines.append(f"- Name: {tool['tool_name']}") |
| 469 | - lines.append(f"- 描述: {tool['tool_description']}") | 469 | + lines.append(f"- Description: {tool['tool_description']}") |
| 470 | if tool['categories']: | 470 | if tool['categories']: |
| 471 | cat = tool['categories'][0] | 471 | cat = tool['categories'][0] |
| 472 | - lines.append(f"- 分类: `{cat['id']}` ({cat['name']})") | 472 | + lines.append(f"- Category: `{cat['id']}` ({cat['name']})") |
| 473 | lines.append("") | 473 | lines.append("") |
| 474 | if len(error['wrong_tools_detail']) > 3: | 474 | if len(error['wrong_tools_detail']) > 3: |
| 475 | - lines.append(f"... 还有 {len(error['wrong_tools_detail']) - 3} 个错误工具\n") | 475 | + lines.append(f"... {len(error['wrong_tools_detail']) - 3} more wrong tool(s)\n") |
| 476 | else: | 476 | else: |
| 477 | - lines.append("**错误工具**: 无\n") | 477 | + lines.append("**Wrong tool**: none\n") |
| 478 | 478 | ||
| 479 | lines.append("---\n") | 479 | lines.append("---\n") |
| 480 | 480 | ||
| @@ -482,51 +482,51 @@ def format_report_markdown(analysis: Dict[str, Any]) -> str: | |||
| 482 | mixed_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'mixed'] | 482 | mixed_errors = [e for e in analysis['detailed_errors'] if e['error_type'] == 'mixed'] |
| 483 | if mixed_errors: | 483 | if mixed_errors: |
| 484 | lines.append("---") | 484 | lines.append("---") |
| 485 | - lines.append("# Mixed: 混合错误 (部分A + 部分B)\n") | 485 | + lines.append("# Mixed: mixed errors (partial A + partial B)\n") |
| 486 | for i, error in enumerate(mixed_errors): | 486 | for i, error in enumerate(mixed_errors): |
| 487 | lines.append(f"## {i+1}. {error['query_id']}\n") | 487 | lines.append(f"## {i+1}. {error['query_id']}\n") |
| 488 | - lines.append(f"**请求内容**: {error['query']}\n") | 488 | + lines.append(f"**Query**: {error['query']}\n") |
| 489 | 489 | ||
| 490 | # Category A missed tools | 490 | # Category A missed tools |
| 491 | if error['missed_tools_A_navigation']: | 491 | if error['missed_tools_A_navigation']: |
| 492 | - lines.append("### A类错误 (没有进入正确分类):\n") | 492 | + lines.append("### Category A error (did not enter the correct category):\n") |
| 493 | for tool in error['missed_tools_A_navigation']: | 493 | for tool in error['missed_tools_A_navigation']: |
| 494 | - lines.append("**正确工具**:") | 494 | + lines.append("**Correct tool**:") |
| 495 | lines.append(f"- ID: `{tool['tool_id']}`") | 495 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 496 | - lines.append(f"- 名称: {tool['tool_name']}") | 496 | + lines.append(f"- Name: {tool['tool_name']}") |
| 497 | - lines.append(f"- 描述: {tool['tool_description']}") | 497 | + lines.append(f"- Description: {tool['tool_description']}") |
| 498 | if tool['correct_categories']: | 498 | if tool['correct_categories']: |
| 499 | - lines.append("**正确工具分类**:") | 499 | + lines.append("**Correct tool category**:") |
| 500 | for cat in tool['correct_categories']: | 500 | for cat in tool['correct_categories']: |
| 501 | lines.append(f"- ID: `{cat['id']}`") | 501 | lines.append(f"- ID: `{cat['id']}`") |
| 502 | - lines.append(f"- 名称: {cat['name']}") | 502 | + lines.append(f"- Name: {cat['name']}") |
| 503 | lines.append("") | 503 | lines.append("") |
| 504 | 504 | ||
| 505 | # Category B missed tools | 505 | # Category B missed tools |
| 506 | if error['missed_tools_B_selection']: | 506 | if error['missed_tools_B_selection']: |
| 507 | - lines.append("### B类错误 (进入正确分类但没选择):\n") | 507 | + lines.append("### Category B error (entered the correct category but did not select):\n") |
| 508 | for tool in error['missed_tools_B_selection']: | 508 | for tool in error['missed_tools_B_selection']: |
| 509 | - lines.append("**正确工具**:") | 509 | + lines.append("**Correct tool**:") |
| 510 | lines.append(f"- ID: `{tool['tool_id']}`") | 510 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 511 | - lines.append(f"- 名称: {tool['tool_name']}") | 511 | + lines.append(f"- Name: {tool['tool_name']}") |
| 512 | - lines.append(f"- 描述: {tool['tool_description']}") | 512 | + lines.append(f"- Description: {tool['tool_description']}") |
| 513 | if tool['correct_categories']: | 513 | if tool['correct_categories']: |
| 514 | - lines.append("**正确工具分类**:") | 514 | + lines.append("**Correct tool category**:") |
| 515 | for cat in tool['correct_categories']: | 515 | for cat in tool['correct_categories']: |
| 516 | lines.append(f"- ID: `{cat['id']}`") | 516 | lines.append(f"- ID: `{cat['id']}`") |
| 517 | - lines.append(f"- 名称: {cat['name']}") | 517 | + lines.append(f"- Name: {cat['name']}") |
| 518 | - lines.append(f"**已访问的正确分类**: {tool['visited_correct_categories']}") | 518 | + lines.append(f"**Visited correct category**: {tool['visited_correct_categories']}") |
| 519 | lines.append("") | 519 | lines.append("") |
| 520 | 520 | ||
| 521 | - # 错误工具 | 521 | + # wrong tools |
| 522 | if error['wrong_tools_detail']: | 522 | if error['wrong_tools_detail']: |
| 523 | - lines.append("**错误工具**:") | 523 | + lines.append("**Wrong tool**:") |
| 524 | for tool in error['wrong_tools_detail'][:3]: | 524 | for tool in error['wrong_tools_detail'][:3]: |
| 525 | lines.append(f"- ID: `{tool['tool_id']}`") | 525 | lines.append(f"- ID: `{tool['tool_id']}`") |
| 526 | - lines.append(f"- 名称: {tool['tool_name']}") | 526 | + lines.append(f"- Name: {tool['tool_name']}") |
| 527 | if tool['categories']: | 527 | if tool['categories']: |
| 528 | cat = tool['categories'][0] | 528 | cat = tool['categories'][0] |
| 529 | - lines.append(f"- 分类: `{cat['id']}` ({cat['name']})") | 529 | + lines.append(f"- Category: `{cat['id']}` ({cat['name']})") |
| 530 | lines.append("") | 530 | lines.append("") |
| 531 | 531 | ||
| 532 | lines.append("---\n") | 532 | lines.append("---\n") |
| @@ -3,7 +3,9 @@ | |||
| 3 | Per-namespace opt-in: a registry remains fully anonymous until | 3 | Per-namespace opt-in: a registry remains fully anonymous until |
| 4 | ``a2x-registry auth init`` runs, and individual namespaces stay anonymous | 4 | ``a2x-registry auth init`` runs, and individual namespaces stay anonymous |
| 5 | unless they were created with ``auth_required=true``. See | 5 | unless they were created with ``auth_required=true``. See |
| 6 | -``docs/auth_design.md`` for the full design. | 6 | +``reference/分析报告/auth_design_sequence.md`` for the full design |
| 7 | +(path contains non-ASCII characters and is retained as-is per the | ||
| 8 | +upstream reference tree layout). | ||
| 7 | 9 | ||
| 8 | Public API: | 10 | Public API: |
| 9 | - ``AuthStore`` — file-backed credential store | 11 | - ``AuthStore`` — file-backed credential store |
| @@ -2,9 +2,26 @@ | |||
| 2 | 2 | ||
| 3 | Usage: | 3 | Usage: |
| 4 | a2x-registry # API on http://127.0.0.1:8000 | 4 | a2x-registry # API on http://127.0.0.1:8000 |
| 5 | - a2x-registry --port 8080 # Custom port | 5 | + a2x-registry --port 8080 # Port override (env wins if set) |
| 6 | python -m a2x_registry.backend # equivalent module-form invocation | 6 | python -m a2x_registry.backend # equivalent module-form invocation |
| 7 | 7 | ||
| 8 | +Listen address comes from ``registry.env`` (env vars), NOT a CLI flag: | ||
| 9 | + | ||
| 10 | + A2X_REGISTRY_MODE "" (generic) | "appliance" | ||
| 11 | + A2X_REGISTRY_BIND empty -> 127.0.0.1 ; concrete IP ; 0.0.0.0 forbidden | ||
| 12 | + A2X_REGISTRY_PORT empty -> 8000 | ||
| 13 | + A2X_REGISTRY_HA_MEMBERS must be empty (single-node SQLite only) | ||
| 14 | + A2X_REGISTRY_DB_KIND empty -> sqlite | "memory" (debug) | "etcd" (appliance only) | ||
| 15 | + A2X_REGISTRY_DB_ENDPOINT http(s):// URL — required when DB_KIND=etcd | ||
| 16 | + A2X_REGISTRY_ETCD_NAMESPACE key prefix; default a2x-registry | ||
| 17 | + A2X_REGISTRY_ETCD_TLS_CA / _CERT / _KEY — all set -> mTLS, all empty -> no auth | ||
| 18 | + A2X_REGISTRY_TLS_CERTFILE / _KEYFILE / _CA_CERTS | ||
| 19 | + all empty -> http ; all three set -> mutual TLS | ||
| 20 | + A2X_REGISTRY_LOG_DIR empty -> stderr only (journalctl) ; else daily files here | ||
| 21 | + (a2x-registry.log for today; rotated -> a2x-registry-YYYY-MM-DD.log.gz) | ||
| 22 | + A2X_REGISTRY_LOG_RETENTION_DAYS | ||
| 23 | + daily-rotated .gz files to keep (default 7) | ||
| 24 | + | ||
| 8 | Auth admin subcommands (no server needed): | 25 | Auth admin subcommands (no server needed): |
| 9 | a2x-registry auth init # bootstrap first admin key | 26 | a2x-registry auth init # bootstrap first admin key |
| 10 | a2x-registry auth reset-admin --confirm # rotate the bootstrap admin | 27 | a2x-registry auth reset-admin --confirm # rotate the bootstrap admin |
| @@ -14,43 +31,279 @@ Cluster subcommands (distributed sync): | |||
| 14 | a2x-registry cluster status # show sync state | 31 | a2x-registry cluster status # show sync state |
| 15 | """ | 32 | """ |
| 16 | 33 | ||
| 34 | +from __future__ import annotations | ||
| 35 | + | ||
| 17 | import argparse | 36 | import argparse |
| 37 | +import logging | ||
| 38 | +import os | ||
| 18 | import sys | 39 | import sys |
| 40 | +from dataclasses import dataclass | ||
| 41 | +from pathlib import Path | ||
| 42 | +from typing import Tuple | ||
| 43 | + | ||
| 44 | +from a2x_registry.backend.startup import VALID_DB_KINDS | ||
| 45 | +from a2x_registry.common.log import DailyCompressedFileHandler | ||
| 19 | 46 | ||
| 20 | 47 | ||
| 21 | -def _serve(argv): | 48 | +# ── env var names ──────────────────────────────────────────────────────── |
| 22 | - """Original 'start server' path. Kept argv-explicit so the dispatcher | 49 | +_ENV_MODE = "A2X_REGISTRY_MODE" |
| 23 | - below can hand it a slice without ``auth`` consuming the world. | 50 | +_ENV_BIND = "A2X_REGISTRY_BIND" |
| 51 | +_ENV_PORT = "A2X_REGISTRY_PORT" | ||
| 52 | +_ENV_HA_MEMBERS = "A2X_REGISTRY_HA_MEMBERS" | ||
| 53 | +_ENV_DB_KIND = "A2X_REGISTRY_DB_KIND" | ||
| 54 | +_ENV_TLS_CERTFILE = "A2X_REGISTRY_TLS_CERTFILE" | ||
| 55 | +_ENV_TLS_KEYFILE = "A2X_REGISTRY_TLS_KEYFILE" | ||
| 56 | +_ENV_TLS_CA_CERTS = "A2X_REGISTRY_TLS_CA_CERTS" | ||
| 57 | +_ENV_LOG_DIR = "A2X_REGISTRY_LOG_DIR" | ||
| 58 | +_ENV_LOG_RETENTION_DAYS = "A2X_REGISTRY_LOG_RETENTION_DAYS" | ||
| 59 | + | ||
| 60 | +_VALID_MODES = ("", "appliance") | ||
| 61 | +_DEFAULT_BIND = "127.0.0.1" | ||
| 62 | +_DEFAULT_PORT = 8000 | ||
| 63 | +_FORBIDDEN_BIND = "0.0.0.0" | ||
| 64 | + | ||
| 65 | + | ||
| 66 | +@dataclass(frozen=True) | ||
| 67 | +class RuntimeConfig: | ||
| 68 | + """Resolved runtime config from env + CLI overrides. | ||
| 69 | + | ||
| 70 | + - ``mode``: "" (generic, service table only) or "appliance" (also | ||
| 71 | + creates image / instance registries at startup). | ||
| 72 | + - ``bind``: concrete listen IP. Never "0.0.0.0" (binds | ||
| 73 | + to a specific interface or loopback only). | ||
| 74 | + - ``port``: listen port. | ||
| 75 | + - ``ha_members``: tuple of peer addresses; must be empty | ||
| 76 | + (single-node only). Non-empty indicates a later distributed | ||
| 77 | + (etcd) release. | ||
| 78 | + - ``db_kind``: storage backend kind - ``sqlite`` (production single-node, | ||
| 79 | + file-persisted) or ``memory`` (debug only, in-process, lost on exit). | ||
| 80 | + ``etcd`` (distributed shared-store) is appliance-only; endpoint / | ||
| 81 | + namespace / TLS for it are validated in ``startup._resolve_db_config``. | ||
| 82 | + Empty env var defaults to ``sqlite``. | ||
| 83 | + - ``tls_certfile`` / ``tls_keyfile`` / ``tls_ca_certs``: mTLS material. | ||
| 84 | + All empty -> plain http. All three set -> mutual TLS (the server | ||
| 85 | + requires + verifies the caller's client cert). Partial config is | ||
| 86 | + rejected in ``parse_runtime_config``. | ||
| 87 | + - ``log_dir``: directory for daily-rotating log files; empty disables | ||
| 88 | + file logging (logs still go to stderr, so journalctl keeps working). | ||
| 89 | + The current day's file is fixed as ``a2x-registry.log``; rotated days | ||
| 90 | + are archived as ``a2x-registry-YYYY-MM-DD.log.gz``. | ||
| 91 | + - ``log_retention_days``: how many daily-rotated files to keep. | ||
| 92 | + """ | ||
| 93 | + | ||
| 94 | + mode: str | ||
| 95 | + bind: str | ||
| 96 | + port: int | ||
| 97 | + ha_members: Tuple[str, ...] | ||
| 98 | + db_kind: str | ||
| 99 | + tls_certfile: str = "" | ||
| 100 | + tls_keyfile: str = "" | ||
| 101 | + tls_ca_certs: str = "" | ||
| 102 | + log_dir: str = "" | ||
| 103 | + log_retention_days: int = 7 | ||
| 104 | + | ||
| 105 | + | ||
| 106 | +def parse_runtime_config() -> RuntimeConfig: | ||
| 107 | + """Parse runtime config from environment variables. | ||
| 108 | + | ||
| 109 | + Raises ``ValueError`` on: | ||
| 110 | + - unknown ``A2X_REGISTRY_MODE`` (only "" / "appliance" valid) | ||
| 111 | + - ``A2X_REGISTRY_BIND=0.0.0.0`` (wildcard forbidden) | ||
| 112 | + - noninteger ``A2X_REGISTRY_PORT`` | ||
| 113 | + - non-empty ``A2X_REGISTRY_HA_MEMBERS`` (single-node only) | ||
| 114 | + - unknown ``A2X_REGISTRY_DB_KIND`` (only sqlite / memory) | ||
| 115 | + """ | ||
| 116 | + mode = os.environ.get(_ENV_MODE, "").strip() | ||
| 117 | + if mode not in _VALID_MODES: | ||
| 118 | + raise ValueError( | ||
| 119 | + f"unknown A2X_REGISTRY_MODE={mode!r}; " | ||
| 120 | + f"accepts only '' (generic) or 'appliance'" | ||
| 121 | + ) | ||
| 122 | + | ||
| 123 | + bind = os.environ.get(_ENV_BIND, "").strip() or _DEFAULT_BIND | ||
| 124 | + if bind == _FORBIDDEN_BIND: | ||
| 125 | + raise ValueError( | ||
| 126 | + "A2X_REGISTRY_BIND=0.0.0.0 is forbidden; " | ||
| 127 | + "bind to a concrete interface or 127.0.0.1" | ||
| 128 | + ) | ||
| 129 | + | ||
| 130 | + port_raw = os.environ.get(_ENV_PORT, "").strip() | ||
| 131 | + if port_raw: | ||
| 132 | + try: | ||
| 133 | + port = int(port_raw) | ||
| 134 | + except ValueError as exc: | ||
| 135 | + raise ValueError( | ||
| 136 | + f"A2X_REGISTRY_PORT={port_raw!r} is not an integer" | ||
| 137 | + ) from exc | ||
| 138 | + if port <= 0 or port > 65535: | ||
| 139 | + raise ValueError(f"A2X_REGISTRY_PORT={port} out of range (1-65535)") | ||
| 140 | + else: | ||
| 141 | + port = _DEFAULT_PORT | ||
| 142 | + | ||
| 143 | + ha_raw = os.environ.get(_ENV_HA_MEMBERS, "") | ||
| 144 | + ha_members = tuple(m.strip() for m in ha_raw.split(",") if m.strip()) | ||
| 145 | + if ha_members: | ||
| 146 | + raise ValueError( | ||
| 147 | + "A2X_REGISTRY_HA_MEMBERS is non-empty but current build is " | ||
| 148 | + "single-node; distributed etcd backend is a later release" | ||
| 149 | + ) | ||
| 150 | + | ||
| 151 | + db_kind = os.environ.get(_ENV_DB_KIND, "").strip() or "sqlite" | ||
| 152 | + if db_kind not in VALID_DB_KINDS: | ||
| 153 | + raise ValueError( | ||
| 154 | + f"unknown A2X_REGISTRY_DB_KIND={db_kind!r}; " | ||
| 155 | + f"accepted values: {', '.join(VALID_DB_KINDS)}" | ||
| 156 | + ) | ||
| 157 | + if db_kind == "etcd" and mode != "appliance": | ||
| 158 | + raise ValueError( | ||
| 159 | + "A2X_REGISTRY_DB_KIND=etcd requires A2X_REGISTRY_MODE=appliance" | ||
| 160 | + ) | ||
| 161 | + | ||
| 162 | + tls_certfile = os.environ.get(_ENV_TLS_CERTFILE, "").strip() | ||
| 163 | + tls_keyfile = os.environ.get(_ENV_TLS_KEYFILE, "").strip() | ||
| 164 | + tls_ca_certs = os.environ.get(_ENV_TLS_CA_CERTS, "").strip() | ||
| 165 | + _tls_set = (bool(tls_certfile), bool(tls_keyfile), bool(tls_ca_certs)) | ||
| 166 | + if any(_tls_set) and not all(_tls_set): | ||
| 167 | + raise ValueError( | ||
| 168 | + "A2X_REGISTRY_TLS_CERTFILE / _KEYFILE / _CA_CERTS must all be set " | ||
| 169 | + "together (enables mutual TLS) or all empty (plain http)" | ||
| 170 | + ) | ||
| 171 | + for _name, _path in ( | ||
| 172 | + (_ENV_TLS_CERTFILE, tls_certfile), | ||
| 173 | + (_ENV_TLS_KEYFILE, tls_keyfile), | ||
| 174 | + (_ENV_TLS_CA_CERTS, tls_ca_certs), | ||
| 175 | + ): | ||
| 176 | + if _path and not os.path.isfile(_path): | ||
| 177 | + raise ValueError(f"{_name}={_path!r} file not found") | ||
| 178 | + | ||
| 179 | + log_dir = os.environ.get(_ENV_LOG_DIR, "").strip() | ||
| 180 | + retention_raw = os.environ.get(_ENV_LOG_RETENTION_DAYS, "").strip() or "7" | ||
| 181 | + try: | ||
| 182 | + log_retention_days = int(retention_raw) | ||
| 183 | + except ValueError as exc: | ||
| 184 | + raise ValueError( | ||
| 185 | + f"A2X_REGISTRY_LOG_RETENTION_DAYS={retention_raw!r} is not an integer" | ||
| 186 | + ) from exc | ||
| 187 | + if log_retention_days < 1: | ||
| 188 | + raise ValueError("A2X_REGISTRY_LOG_RETENTION_DAYS must be >= 1") | ||
| 189 | + | ||
| 190 | + return RuntimeConfig( | ||
| 191 | + mode=mode, bind=bind, port=port, | ||
| 192 | + ha_members=ha_members, db_kind=db_kind, | ||
| 193 | + tls_certfile=tls_certfile, tls_keyfile=tls_keyfile, | ||
| 194 | + tls_ca_certs=tls_ca_certs, | ||
| 195 | + log_dir=log_dir, | ||
| 196 | + log_retention_days=log_retention_days, | ||
| 197 | + ) | ||
| 198 | + | ||
| 199 | + | ||
| 200 | +def _build_parser() -> argparse.ArgumentParser: | ||
| 201 | + """Build the serve-mode CLI parser. | ||
| 202 | + | ||
| 203 | + Deliberately omits ``--host``: the listen address is env-driven | ||
| 204 | + (``A2X_REGISTRY_BIND``) so it can be supplied via ``registry.env`` | ||
| 205 | + without touching the systemd ``ExecStart`` line. ``--port`` is kept as | ||
| 206 | + a dev convenience; when both are set, the env var wins (parsed in | ||
| 207 | + ``parse_runtime_config`` before this parser runs). | ||
| 24 | """ | 208 | """ |
| 25 | parser = argparse.ArgumentParser( | 209 | parser = argparse.ArgumentParser( |
| 26 | prog="a2x-registry", | 210 | prog="a2x-registry", |
| 27 | description="A2X Registry — backend API server", | 211 | description="A2X Registry — backend API server", |
| 28 | ) | 212 | ) |
| 29 | - parser.add_argument("--port", type=int, default=8000, help="Port (default: 8000)") | 213 | + parser.add_argument( |
| 30 | - parser.add_argument("--host", type=str, default="127.0.0.1", help="Host (default: 127.0.0.1)") | 214 | + "--port", type=int, default=None, |
| 31 | - parser.add_argument("--reload", action="store_true", default=False, help="Enable auto-reload") | 215 | + help="Port override (A2X_REGISTRY_PORT env wins if set; default 8000)", |
| 32 | - args = parser.parse_args(argv) | 216 | + ) |
| 217 | + parser.add_argument( | ||
| 218 | + "--reload", action="store_true", default=False, | ||
| 219 | + help="Enable auto-reload (dev only)", | ||
| 220 | + ) | ||
| 221 | + parser.add_argument( | ||
| 222 | + "--keep-alive", type=int, default=75, | ||
| 223 | + help="HTTP keep-alive timeout in seconds (default 75; must be >= heartbeat interval)", | ||
| 224 | + ) | ||
| 225 | + return parser | ||
| 33 | 226 | ||
| 34 | - print(f"\n A2X Registry") | ||
| 35 | - print(f" http://{args.host}:{args.port}") | ||
| 36 | - print(f" Docs: http://{args.host}:{args.port}/docs\n") | ||
| 37 | 227 | ||
| 38 | - import uvicorn | 228 | +def _configure_logging(cfg: RuntimeConfig) -> None: |
| 39 | - uvicorn.run( | 229 | + """Route all logs (uvicorn + app) to stderr AND a daily-rotating file. |
| 40 | - "a2x_registry.backend.app:app", | 230 | + |
| 41 | - host=args.host, | 231 | + The stderr handler keeps systemd/journalctl working exactly as before. |
| 42 | - port=args.port, | 232 | + When ``cfg.log_dir`` is set, a ``DailyCompressedFileHandler`` writes the |
| 43 | - reload=args.reload, | 233 | + fixed-name file ``a2x-registry.log`` for the current day, gzips the |
| 234 | + finished day's file to ``a2x-registry-YYYY-MM-DD.log.gz`` on rotation, | ||
| 235 | + and keeps ``log_retention_days`` old compressed files. | ||
| 236 | + ``uvicorn.run(log_config=None)`` leaves this root-level | ||
| 237 | + config in place, so uvicorn's own loggers (``uvicorn`` / ``uvicorn.error`` | ||
| 238 | + / ``uvicorn.access``) propagate here and land in both sinks. | ||
| 239 | + """ | ||
| 240 | + handlers: list = [logging.StreamHandler(sys.stderr)] | ||
| 241 | + if cfg.log_dir: | ||
| 242 | + log_dir = Path(cfg.log_dir) | ||
| 243 | + log_dir.mkdir(parents=True, exist_ok=True) | ||
| 244 | + handlers.append( | ||
| 245 | + DailyCompressedFileHandler(log_dir, "a2x-registry", cfg.log_retention_days) | ||
| 246 | + ) | ||
| 247 | + logging.basicConfig( | ||
| 248 | + level=logging.INFO, | ||
| 249 | + format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", | ||
| 250 | + handlers=handlers, | ||
| 251 | + force=True, | ||
| 44 | ) | 252 | ) |
| 45 | 253 | ||
| 46 | 254 | ||
| 47 | -def main(): | 255 | +def _serve(argv) -> None: |
| 48 | - """Top-level dispatch: when ``argv[1] == 'auth'``, route to the auth | 256 | + """Start the uvicorn server using env-driven config. |
| 49 | - CLI; otherwise run the original ``serve`` path. This keeps every | 257 | + |
| 50 | - pre-existing invocation (`a2x-registry`, `a2x-registry --port 8080`) | 258 | + ``--port`` on the CLI is a fallback only; ``A2X_REGISTRY_PORT`` env |
| 51 | - byte-identical to before, while adding the new ``auth`` subcommand | 259 | + var takes precedence so ``registry.env`` remains the single source of |
| 52 | - behind a single positional discriminator. | 260 | + truth for deployment. |
| 53 | """ | 261 | """ |
| 262 | + parser = _build_parser() | ||
| 263 | + args = parser.parse_args(argv) | ||
| 264 | + | ||
| 265 | + cfg = parse_runtime_config() | ||
| 266 | + # CLI --port is a dev fallback; env var (already in cfg) wins when set. | ||
| 267 | + port = cfg.port if os.environ.get(_ENV_PORT, "").strip() else (args.port or cfg.port) | ||
| 268 | + | ||
| 269 | + scheme = "https" if cfg.tls_certfile else "http" | ||
| 270 | + print(f"\n A2X Registry") | ||
| 271 | + print(f" {scheme}://{cfg.bind}:{port}") | ||
| 272 | + print(f" Docs: {scheme}://{cfg.bind}:{port}/docs\n") | ||
| 273 | + | ||
| 274 | + ssl_kwargs = {} | ||
| 275 | + if cfg.tls_certfile: | ||
| 276 | + import ssl | ||
| 277 | + # Mutual TLS: require + verify the caller's client certificate. | ||
| 278 | + ssl_kwargs = dict( | ||
| 279 | + ssl_certfile=cfg.tls_certfile, | ||
| 280 | + ssl_keyfile=cfg.tls_keyfile, | ||
| 281 | + ssl_ca_certs=cfg.tls_ca_certs, | ||
| 282 | + ssl_cert_reqs=ssl.CERT_REQUIRED, | ||
| 283 | + ) | ||
| 284 | + | ||
| 285 | + import signal | ||
| 286 | + # SIGTERM (systemctl stop): exit cleanly with code 0 instead of being | ||
| 287 | + # killed by the default disposition (exit code 15). Covers the import / | ||
| 288 | + # startup window; once the server loop runs, uvicorn's own handler takes | ||
| 289 | + # over and also shuts down gracefully. | ||
| 290 | + signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) | ||
| 291 | + | ||
| 292 | + import uvicorn | ||
| 293 | + _configure_logging(cfg) | ||
| 294 | + uvicorn.run( | ||
| 295 | + "a2x_registry.backend.app:app", | ||
| 296 | + host=cfg.bind, | ||
| 297 | + port=port, | ||
| 298 | + reload=args.reload, | ||
| 299 | + timeout_keep_alive=args.keep_alive, | ||
| 300 | + log_config=None, # keep our root-level config (stderr + optional file) | ||
| 301 | + **ssl_kwargs, | ||
| 302 | + ) | ||
| 303 | + | ||
| 304 | + | ||
| 305 | +def main() -> None: | ||
| 306 | + """Top-level dispatch: route ``auth`` / ``cluster`` subcommands, else serve.""" | ||
| 54 | if len(sys.argv) >= 2 and sys.argv[1] == "auth": | 307 | if len(sys.argv) >= 2 and sys.argv[1] == "auth": |
| 55 | from a2x_registry.auth.cli import main as auth_main | 308 | from a2x_registry.auth.cli import main as auth_main |
| 56 | sys.exit(auth_main(sys.argv[2:])) | 309 | sys.exit(auth_main(sys.argv[2:])) |
| @@ -17,6 +17,8 @@ from a2x_registry.common.errors import FeatureNotInstalledError, LLMNotConfigure | |||
| 17 | from a2x_registry.auth.router import router as auth_router | 17 | from a2x_registry.auth.router import router as auth_router |
| 18 | from a2x_registry.heartbeat.router import router as heartbeat_router | 18 | from a2x_registry.heartbeat.router import router as heartbeat_router |
| 19 | from a2x_registry.cluster.router import router as cluster_router | 19 | from a2x_registry.cluster.router import router as cluster_router |
| 20 | +from a2x_registry.image.router import router as image_router | ||
| 21 | +from a2x_registry.instance.router import router as instance_router | ||
| 20 | 22 | ||
| 21 | app = FastAPI( | 23 | app = FastAPI( |
| 22 | title="A2X Registry Demo", | 24 | title="A2X Registry Demo", |
| @@ -39,12 +41,24 @@ app.include_router(provider.router) | |||
| 39 | # /api/auth/* — the router itself returns 404 when auth is not initialized, | 41 | # /api/auth/* — the router itself returns 404 when auth is not initialized, |
| 40 | # so mounting it unconditionally is safe and keeps the app graph simple. | 42 | # so mounting it unconditionally is safe and keeps the app graph simple. |
| 41 | app.include_router(auth_router) | 43 | app.include_router(auth_router) |
| 42 | -# Heartbeat endpoints. Same 404 fallback semantics when the heartbeat | 44 | +# Heartbeat endpoints (per-service lease, A2X backward-compat). The |
| 43 | -# module isn't initialized (e.g. lite mode without startup hook). | 45 | +# router itself returns 404 when the heartbeat module isn't initialized, |
| 46 | +# so mounting it unconditionally is safe. | ||
| 47 | +# NOTE: per-node heartbeat (/api/nodes/{node}/heartbeat, /api/lease-config) | ||
| 48 | +# was removed — instance liveness is now reported by the | ||
| 49 | +# gateway via PATCH status (据元戎 List). | ||
| 44 | app.include_router(heartbeat_router) | 50 | app.include_router(heartbeat_router) |
| 45 | # Cluster (distributed sync) endpoints. Opt-in: every route 404s until the | 51 | # Cluster (distributed sync) endpoints. Opt-in: every route 404s until the |
| 46 | # cluster module is initialized (cluster_state.json present at startup). | 52 | # cluster module is initialized (cluster_state.json present at startup). |
| 47 | app.include_router(cluster_router) | 53 | app.include_router(cluster_router) |
| 54 | +# Image management endpoints. Accessible only after appliance-mode | ||
| 55 | +# assembly; when not assembled, _resolve_service in the router returns | ||
| 56 | +# 404 (same fallback semantics as heartbeat/cluster). | ||
| 57 | +app.include_router(image_router) | ||
| 58 | +# Instance management endpoints. Accessible only after appliance-mode | ||
| 59 | +# assembly; when not assembled, _resolve_service in the router returns | ||
| 60 | +# 404 (same fallback semantics as heartbeat/cluster/image). | ||
| 61 | +app.include_router(instance_router) | ||
| 48 | 62 | ||
| 49 | 63 | ||
| 50 | @app.exception_handler(FeatureNotInstalledError) | 64 | @app.exception_handler(FeatureNotInstalledError) |
| @@ -116,7 +130,10 @@ async def _shutdown(): | |||
| 116 | # sweeper tick can't submit to an already-shut-down pool or use a closed | 130 | # sweeper tick can't submit to an already-shut-down pool or use a closed |
| 117 | # HTTP client. | 131 | # HTTP client. |
| 118 | from a2x_registry.backend.startup import warmup_state | 132 | from a2x_registry.backend.startup import warmup_state |
| 119 | - for key in ("_cluster_anti_entropy", "_cluster_keepalive", "_heartbeat_sweeper"): | 133 | + for key in ( |
| 134 | + "_cluster_anti_entropy", "_cluster_keepalive", | ||
| 135 | + "_heartbeat_sweeper", | ||
| 136 | + ): | ||
| 120 | sweeper = warmup_state.get(key) | 137 | sweeper = warmup_state.get(key) |
| 121 | if sweeper is not None: | 138 | if sweeper is not None: |
| 122 | try: | 139 | try: |
| @@ -79,7 +79,7 @@ async def trigger_build( | |||
| 79 | _cancel_flags[dataset] = stop_event | 79 | _cancel_flags[dataset] = stop_event |
| 80 | _build_jobs[dataset] = { | 80 | _build_jobs[dataset] = { |
| 81 | "status": "running", | 81 | "status": "running", |
| 82 | - "message": "构建中,请稍候...", | 82 | + "message": "Building, please wait...", |
| 83 | "started_at": time.time(), | 83 | "started_at": time.time(), |
| 84 | "finished_at": None, | 84 | "finished_at": None, |
| 85 | "logs": [], | 85 | "logs": [], |
| @@ -87,7 +87,7 @@ async def trigger_build( | |||
| 87 | extra = {k: v for k, v in req.model_dump().items() | 87 | extra = {k: v for k, v in req.model_dump().items() |
| 88 | if k != "resume" and v is not None} | 88 | if k != "resume" and v is not None} |
| 89 | background_tasks.add_task(_run_taxonomy_build, dataset, req.resume, extra, stop_event) | 89 | background_tasks.add_task(_run_taxonomy_build, dataset, req.resume, extra, stop_event) |
| 90 | - return {"dataset": dataset, "status": "started", "message": "构建已启动"} | 90 | + return {"dataset": dataset, "status": "started", "message": "Build started"} |
| 91 | 91 | ||
| 92 | 92 | ||
| 93 | # --------------------------------------------------------------------------- | 93 | # --------------------------------------------------------------------------- |
| @@ -118,7 +118,7 @@ async def cancel_build( | |||
| 118 | event = _cancel_flags.get(dataset) | 118 | event = _cancel_flags.get(dataset) |
| 119 | if event: | 119 | if event: |
| 120 | event.set() | 120 | event.set() |
| 121 | - msg = "构建已取消" | 121 | + msg = "Build cancelled" |
| 122 | _build_jobs[dataset].update({"status": "cancelled", "message": msg, "finished_at": time.time()}) | 122 | _build_jobs[dataset].update({"status": "cancelled", "message": msg, "finished_at": time.time()}) |
| 123 | _push_to_subs(dataset, {"type": "status", "status": "cancelled", "message": msg}) | 123 | _push_to_subs(dataset, {"type": "status", "status": "cancelled", "message": msg}) |
| 124 | return {"dataset": dataset, "status": "cancelled", "message": msg} | 124 | return {"dataset": dataset, "status": "cancelled", "message": msg} |
| @@ -235,8 +235,8 @@ def _run_taxonomy_build(dataset: str, resume: str, extra_params: dict = None, | |||
| 235 | builder.build(resume=resume) | 235 | builder.build(resume=resume) |
| 236 | # If cancel_build() already updated the job, don't overwrite with "done" | 236 | # If cancel_build() already updated the job, don't overwrite with "done" |
| 237 | if job.get("status") == "running": | 237 | if job.get("status") == "running": |
| 238 | - job.update({"status": "done", "message": "分类树构建完成", "finished_at": time.time()}) | 238 | + job.update({"status": "done", "message": "Taxonomy build complete", "finished_at": time.time()}) |
| 239 | - _push_to_subs(dataset, {"type": "status", "status": "done", "message": "分类树构建完成"}) | 239 | + _push_to_subs(dataset, {"type": "status", "status": "done", "message": "Taxonomy build complete"}) |
| 240 | except InterruptedError: | 240 | except InterruptedError: |
| 241 | pass # cancel_build() already set status and pushed SSE event | 241 | pass # cancel_build() already set status and pushed SSE event |
| 242 | except Exception as e: | 242 | except Exception as e: |
| @@ -47,10 +47,10 @@ except ValueError: | |||
| 47 | _executor = ThreadPoolExecutor(max_workers=_DATASET_WORKERS) | 47 | _executor = ThreadPoolExecutor(max_workers=_DATASET_WORKERS) |
| 48 | 48 | ||
| 49 | 49 | ||
| 50 | -def init_registry_service(database_dir: Path, global_config_path: Optional[Path] = None): | 50 | +def init_registry_service(database_dir: Path): |
| 51 | """Initialize the global RegistryService. Called once from backend startup.""" | 51 | """Initialize the global RegistryService. Called once from backend startup.""" |
| 52 | global _service | 52 | global _service |
| 53 | - _service = RegistryService(database_dir, global_config_path) | 53 | + _service = RegistryService(database_dir) |
| 54 | return _service | 54 | return _service |
| 55 | 55 | ||
| 56 | 56 | ||
| @@ -64,7 +64,7 @@ def get_registry_service() -> RegistryService: | |||
| 64 | async def _run(fn, *args): | 64 | async def _run(fn, *args): |
| 65 | """Run a blocking function in the thread pool, mapping exceptions to HTTP errors. | 65 | """Run a blocking function in the thread pool, mapping exceptions to HTTP errors. |
| 66 | 66 | ||
| 67 | - Layered error contract (see docs/client_design.md §3.4): | 67 | + Layered error contract: |
| 68 | RegistryNotFoundError → 404 (business "resource doesn't exist") | 68 | RegistryNotFoundError → 404 (business "resource doesn't exist") |
| 69 | HeartbeatError → 400 + structured body {code, min_ttl?, max_ttl?} | 69 | HeartbeatError → 400 + structured body {code, min_ttl?, max_ttl?} |
| 70 | ValueError → 400 (validation / forbidden source) | 70 | ValueError → 400 (validation / forbidden source) |
| @@ -909,4 +909,4 @@ async def set_vector_config( | |||
| 909 | dataset, body.get("embedding_model"), body.get("embedding_dim"), | 909 | dataset, body.get("embedding_model"), body.get("embedding_dim"), |
| 910 | ) | 910 | ) |
| 911 | search_service.schedule_vector_sync(dataset) | 911 | search_service.schedule_vector_sync(dataset) |
| 912 | - return {"dataset": dataset, **cfg, "message": "配置已保存,向量索引将在后台重建"} | 912 | + return {"dataset": dataset, **cfg, "message": "Config saved; vector index will rebuild in background"} |
| @@ -6,6 +6,7 @@ server can begin accepting requests (e.g. /api/warmup-status) while loading. | |||
| 6 | 6 | ||
| 7 | import logging | 7 | import logging |
| 8 | import time | 8 | import time |
| 9 | +from typing import Optional | ||
| 9 | 10 | ||
| 10 | from a2x_registry.common.paths import database_dir | 11 | from a2x_registry.common.paths import database_dir |
| 11 | from a2x_registry.common import feature_flags | 12 | from a2x_registry.common import feature_flags |
| @@ -21,6 +22,221 @@ warmup_state: dict = { | |||
| 21 | } | 22 | } |
| 22 | 23 | ||
| 23 | 24 | ||
| 25 | +# ── env var names (storage backend selection) ─────────────────────────── | ||
| 26 | +_ENV_DB_KIND = "A2X_REGISTRY_DB_KIND" | ||
| 27 | +_ENV_DB_ENDPOINT = "A2X_REGISTRY_DB_ENDPOINT" | ||
| 28 | +_ENV_ETCD_NAMESPACE = "A2X_REGISTRY_ETCD_NAMESPACE" | ||
| 29 | +_ENV_ETCD_TLS_CA = "A2X_REGISTRY_ETCD_TLS_CA" | ||
| 30 | +_ENV_ETCD_TLS_CERT = "A2X_REGISTRY_ETCD_TLS_CERT" | ||
| 31 | +_ENV_ETCD_TLS_KEY = "A2X_REGISTRY_ETCD_TLS_KEY" | ||
| 32 | +# How long warmup waits for etcd to accept connections before failing. | ||
| 33 | +# systemd usually starts etcd and this service together; etcd can come up | ||
| 34 | +# slower, and without the wait the first failed probe aborts warmup for | ||
| 35 | +# good (manual restart required). | ||
| 36 | +_ETCD_STARTUP_WAIT_S = 600.0 | ||
| 37 | +_ETCD_RETRY_MAX_DELAY = 10.0 | ||
| 38 | +# Single source of truth for valid storage kinds — ``backend.__main__`` | ||
| 39 | +# (CLI pre-validation) imports this instead of redefining its own tuple. | ||
| 40 | +VALID_DB_KINDS = ("sqlite", "memory", "etcd") | ||
| 41 | + | ||
| 42 | + | ||
| 43 | +def _resolve_db_config() -> dict: | ||
| 44 | + """Build the ``connect(cfg)`` dict from ``A2X_REGISTRY_DB_KIND``. | ||
| 45 | + | ||
| 46 | + - empty/missing -> ``sqlite`` (production single-node, file-persisted at | ||
| 47 | + ``<home>/database/registry.db``). | ||
| 48 | + - ``memory`` -> in-process ``:memory:`` backend (debug only, lost on | ||
| 49 | + process exit); no ``path`` key. | ||
| 50 | + - ``etcd`` -> distributed shared-store backend. Requires | ||
| 51 | + ``A2X_REGISTRY_DB_ENDPOINT`` (single ``http(s)://`` URL); key prefix from | ||
| 52 | + ``A2X_REGISTRY_ETCD_NAMESPACE`` (default ``a2x-registry``). TLS: set | ||
| 53 | + ``A2X_REGISTRY_ETCD_TLS_CA/CERT/KEY`` together -> HTTPS + mutual TLS; | ||
| 54 | + leave all empty -> plain HTTP, no auth. The endpoint scheme must match: | ||
| 55 | + certs configured -> ``https://``, none -> ``http://`` (mismatch is an | ||
| 56 | + error). | ||
| 57 | + | ||
| 58 | + Raises ``ValueError`` on an unknown kind or invalid etcd config so a typo | ||
| 59 | + never silently falls back. Business code never branches on kind - it only | ||
| 60 | + sees the repo returned by ``build_table_repo``. | ||
| 61 | + """ | ||
| 62 | + import os | ||
| 63 | + | ||
| 64 | + kind = os.environ.get(_ENV_DB_KIND, "").strip() or "sqlite" | ||
| 65 | + if kind not in VALID_DB_KINDS: | ||
| 66 | + raise ValueError( | ||
| 67 | + f"unknown A2X_REGISTRY_DB_KIND={kind!r}; " | ||
| 68 | + f"accepted values: {', '.join(VALID_DB_KINDS)}" | ||
| 69 | + ) | ||
| 70 | + if kind == "memory": | ||
| 71 | + return {"kind": "memory"} | ||
| 72 | + if kind == "etcd": | ||
| 73 | + # Lazy import: pulls the (heavy) register package, so only pay it on | ||
| 74 | + # the etcd path; DEFAULT_NAMESPACE is the canonical default the | ||
| 75 | + # EtcdClient itself falls back to. | ||
| 76 | + from a2x_registry.register.etcd_client import DEFAULT_NAMESPACE | ||
| 77 | + | ||
| 78 | + endpoint = os.environ.get(_ENV_DB_ENDPOINT, "").strip() | ||
| 79 | + if not endpoint: | ||
| 80 | + raise ValueError( | ||
| 81 | + "A2X_REGISTRY_DB_ENDPOINT is required when DB_KIND=etcd" | ||
| 82 | + ) | ||
| 83 | + if not endpoint.startswith(("http://", "https://")): | ||
| 84 | + raise ValueError(f"A2X_REGISTRY_DB_ENDPOINT must be http(s)://, got {endpoint!r}") | ||
| 85 | + namespace = ( | ||
| 86 | + os.environ.get(_ENV_ETCD_NAMESPACE, "").strip() | ||
| 87 | + or DEFAULT_NAMESPACE | ||
| 88 | + ) | ||
| 89 | + ca = os.environ.get(_ENV_ETCD_TLS_CA, "").strip() | ||
| 90 | + cert = os.environ.get(_ENV_ETCD_TLS_CERT, "").strip() | ||
| 91 | + key = os.environ.get(_ENV_ETCD_TLS_KEY, "").strip() | ||
| 92 | + tls_set = (bool(ca), bool(cert), bool(key)) | ||
| 93 | + if any(tls_set) and not all(tls_set): | ||
| 94 | + raise ValueError( | ||
| 95 | + "A2X_REGISTRY_ETCD_TLS_CA / _CERT / _KEY must all be set " | ||
| 96 | + "together (mutual TLS) or all empty (no auth)" | ||
| 97 | + ) | ||
| 98 | + if all(tls_set) and not endpoint.startswith("https://"): | ||
| 99 | + raise ValueError( | ||
| 100 | + "etcd certs configured but A2X_REGISTRY_DB_ENDPOINT is not " | ||
| 101 | + "https://; certs require TLS" | ||
| 102 | + ) | ||
| 103 | + return { | ||
| 104 | + "kind": "etcd", | ||
| 105 | + "endpoint": endpoint, | ||
| 106 | + "namespace": namespace, | ||
| 107 | + "ca": ca, "cert": cert, "key": key, | ||
| 108 | + } | ||
| 109 | + # sqlite (default) | ||
| 110 | + db_path = database_dir() / "registry.db" | ||
| 111 | + db_path.parent.mkdir(parents=True, exist_ok=True) | ||
| 112 | + return {"kind": "sqlite", "path": str(db_path)} | ||
| 113 | + | ||
| 114 | + | ||
| 115 | +def _build_yuanrong_client(instance_consts) -> Optional[object]: | ||
| 116 | + """按环境变量构造元戎沙箱客户端;endpoint 空 → None(模式 B 回 501)。 | ||
| 117 | + | ||
| 118 | + 环境变量与默认值见 ``a2x_registry/instance/constants.py``(可配置常量区)。 | ||
| 119 | + 数值非法(非浮点)时抛 ValueError 使启动失败——配置错误应当显式暴露。 | ||
| 120 | + """ | ||
| 121 | + import os | ||
| 122 | + | ||
| 123 | + endpoint = os.environ.get( | ||
| 124 | + instance_consts.YUANRONG_ENDPOINT_ENV, "" | ||
| 125 | + ).strip() | ||
| 126 | + if not endpoint: | ||
| 127 | + return None | ||
| 128 | + | ||
| 129 | + def _float_env(env_name: str, default: float) -> float: | ||
| 130 | + raw = os.environ.get(env_name, "").strip() | ||
| 131 | + if not raw: | ||
| 132 | + return float(default) | ||
| 133 | + try: | ||
| 134 | + return float(raw) | ||
| 135 | + except ValueError as exc: | ||
| 136 | + raise ValueError( | ||
| 137 | + f"{env_name}={raw!r} is not a number" | ||
| 138 | + ) from exc | ||
| 139 | + | ||
| 140 | + from a2x_registry.instance.yuanrong_client import YuanrongSandboxClient | ||
| 141 | + | ||
| 142 | + return YuanrongSandboxClient( | ||
| 143 | + frontend_endpoint=endpoint, | ||
| 144 | + agent_timeout_s=_float_env( | ||
| 145 | + instance_consts.YUANRONG_TIMEOUT_S_ENV, | ||
| 146 | + instance_consts.YUANRONG_TIMEOUT_S_DEFAULT, | ||
| 147 | + ), | ||
| 148 | + agent_namespace=( | ||
| 149 | + os.environ.get( | ||
| 150 | + instance_consts.YUANRONG_NAMESPACE_ENV, "" | ||
| 151 | + ).strip() | ||
| 152 | + or instance_consts.YUANRONG_NAMESPACE_DEFAULT | ||
| 153 | + ), | ||
| 154 | + wait_running_timeout_s=_float_env( | ||
| 155 | + instance_consts.YUANRONG_WAIT_RUNNING_S_ENV, | ||
| 156 | + instance_consts.YUANRONG_WAIT_RUNNING_S_DEFAULT, | ||
| 157 | + ), | ||
| 158 | + wait_running_interval_s=_float_env( | ||
| 159 | + instance_consts.YUANRONG_WAIT_INTERVAL_S_ENV, | ||
| 160 | + instance_consts.YUANRONG_WAIT_INTERVAL_S_DEFAULT, | ||
| 161 | + ), | ||
| 162 | + ) | ||
| 163 | + | ||
| 164 | + | ||
| 165 | +def _wait_for_etcd(client, endpoint: str, wait_s: float) -> None: | ||
| 166 | + """Probe ``client`` until etcd answers, up to ``wait_s`` seconds. | ||
| 167 | + | ||
| 168 | + Covers the systemd race where this unit starts before etcd is ready: | ||
| 169 | + retrying here lets warmup finish once etcd comes up, instead of leaving | ||
| 170 | + the process permanently unassembled until an operator restarts it. | ||
| 171 | + """ | ||
| 172 | + from a2x_registry.register.etcd_client import EtcdError | ||
| 173 | + | ||
| 174 | + logger = logging.getLogger("uvicorn") | ||
| 175 | + started = time.monotonic() | ||
| 176 | + deadline = started + wait_s | ||
| 177 | + delay = 1.0 | ||
| 178 | + attempt = 0 | ||
| 179 | + while True: | ||
| 180 | + try: | ||
| 181 | + client.ping() | ||
| 182 | + if attempt: | ||
| 183 | + logger.info( | ||
| 184 | + " etcd reachable at %s after %.1fs", | ||
| 185 | + endpoint, time.monotonic() - started, | ||
| 186 | + ) | ||
| 187 | + return | ||
| 188 | + except EtcdError as exc: | ||
| 189 | + attempt += 1 | ||
| 190 | + remaining = deadline - time.monotonic() | ||
| 191 | + if remaining <= 0: | ||
| 192 | + raise | ||
| 193 | + logger.warning( | ||
| 194 | + " etcd not reachable at %s yet - retrying in %.0fs " | ||
| 195 | + "(%.0fs left): %s", | ||
| 196 | + endpoint, min(delay, remaining), remaining, exc, | ||
| 197 | + ) | ||
| 198 | + time.sleep(min(delay, remaining)) | ||
| 199 | + delay = min(delay * 2, _ETCD_RETRY_MAX_DELAY) | ||
| 200 | + | ||
| 201 | + | ||
| 202 | +def build_table_repo(cfg: dict): | ||
| 203 | + """Build the storage repo (``TableRepo``) for the resolved config. | ||
| 204 | + | ||
| 205 | + - ``sqlite`` / ``memory``: connect the backend, initialise the schema, wrap | ||
| 206 | + in ``RegistryTableService``. | ||
| 207 | + - ``etcd``: build ``EtcdTableRepo`` on an ``EtcdClient``; probe | ||
| 208 | + connectivity first, retrying for up to 600s so a slow-starting etcd | ||
| 209 | + (systemd start ordering) does not abort startup. Still fails if etcd | ||
| 210 | + never becomes reachable. | ||
| 211 | + | ||
| 212 | + Raises on backend connect / schema / connectivity failure; the caller | ||
| 213 | + decides how to surface it. | ||
| 214 | + """ | ||
| 215 | + if cfg.get("kind") == "etcd": | ||
| 216 | + from a2x_registry.register.etcd_client import ( | ||
| 217 | + DEFAULT_NAMESPACE, | ||
| 218 | + EtcdClient, | ||
| 219 | + ) | ||
| 220 | + from a2x_registry.register.etcd_repo import EtcdTableRepo | ||
| 221 | + | ||
| 222 | + client = EtcdClient( | ||
| 223 | + endpoint=cfg["endpoint"], | ||
| 224 | + namespace=cfg.get("namespace", DEFAULT_NAMESPACE), | ||
| 225 | + ca=cfg.get("ca", ""), | ||
| 226 | + cert=cfg.get("cert", ""), | ||
| 227 | + key=cfg.get("key", ""), | ||
| 228 | + ) | ||
| 229 | + _wait_for_etcd(client, cfg["endpoint"], _ETCD_STARTUP_WAIT_S) | ||
| 230 | + return EtcdTableRepo(client) | ||
| 231 | + | ||
| 232 | + from a2x_registry.common.db import connect, init_schema | ||
| 233 | + from a2x_registry.register.service import RegistryTableService | ||
| 234 | + | ||
| 235 | + backend = connect(cfg) | ||
| 236 | + init_schema(backend.conn) | ||
| 237 | + return RegistryTableService(backend) | ||
| 238 | + | ||
| 239 | + | ||
| 24 | def run_warmup() -> None: | 240 | def run_warmup() -> None: |
| 25 | """Execute the full startup sequence (blocking — run in a thread pool).""" | 241 | """Execute the full startup sequence (blocking — run in a thread pool).""" |
| 26 | import logging | 242 | import logging |
| @@ -40,8 +256,83 @@ def run_warmup() -> None: | |||
| 40 | try: | 256 | try: |
| 41 | t0 = time.time() | 257 | t0 = time.time() |
| 42 | 258 | ||
| 259 | + # 0. SQL backend + RegistryTableService (base assembly). | ||
| 260 | + # image/instance services pick up ``_table_service`` from | ||
| 261 | + # warmup_state instead of re-instantiating their own Backend. | ||
| 262 | + # Failure here is fatal — without the SQL layer image/instance | ||
| 263 | + # modules have no store to bind to. | ||
| 264 | + _stage("Initializing SQL backend...", 2) | ||
| 265 | + try: | ||
| 266 | + import os | ||
| 267 | + | ||
| 268 | + db_cfg = _resolve_db_config() | ||
| 269 | + table_svc = build_table_repo(db_cfg) | ||
| 270 | + | ||
| 271 | + # Register the named registries per startup mode. | ||
| 272 | + # Generic mode: only the A2X backward-compat ``default`` | ||
| 273 | + # service registry. Appliance mode: also create the image / | ||
| 274 | + # instance registries so image/instance routes have a target. | ||
| 275 | + mode = os.environ.get("A2X_REGISTRY_MODE", "").strip() | ||
| 276 | + table_svc.create_registry("default", "service") | ||
| 277 | + if mode == "appliance": | ||
| 278 | + table_svc.create_registry("images", "image") | ||
| 279 | + table_svc.create_registry("instances", "instance") | ||
| 280 | + | ||
| 281 | + warmup_state["_table_service"] = table_svc | ||
| 282 | + logger.info( | ||
| 283 | + " SQL backend ready (kind=%s, mode=%s)", | ||
| 284 | + db_cfg.get("kind"), mode or "generic", | ||
| 285 | + ) | ||
| 286 | + | ||
| 287 | + # Assemble ImageService only in appliance mode (image registry | ||
| 288 | + # already created above). Non-appliance mode skips assembly; | ||
| 289 | + # the router's _resolve_service then returns 404, matching the | ||
| 290 | + # design that generic mode does not create image/instance | ||
| 291 | + # tables. The image module picks up the already-assembled | ||
| 292 | + # RegistryTableService from _table_service. | ||
| 293 | + if mode == "appliance": | ||
| 294 | + from a2x_registry.image.service import ImageService | ||
| 295 | + from a2x_registry.image.deps import set_image_service | ||
| 296 | + from a2x_registry.instance.service import InstanceService | ||
| 297 | + from a2x_registry.instance.deps import set_instance_service | ||
| 298 | + from a2x_registry.instance import constants as instance_consts | ||
| 299 | + from a2x_registry.instance.yuanrong_client import ( | ||
| 300 | + YuanrongSandboxClient, | ||
| 301 | + ) | ||
| 302 | + | ||
| 303 | + image_svc = ImageService(table_svc) | ||
| 304 | + set_image_service(image_svc) | ||
| 305 | + logger.info(" ImageService assembled (appliance mode)") | ||
| 306 | + | ||
| 307 | + # 元戎客户端(可选):endpoint 空 = 未配置,模式 B 请求回 501。 | ||
| 308 | + yuanrong_client = _build_yuanrong_client(instance_consts) | ||
| 309 | + instance_svc = InstanceService( | ||
| 310 | + table_svc, yuanrong_client=yuanrong_client | ||
| 311 | + ) | ||
| 312 | + set_instance_service(instance_svc) | ||
| 313 | + logger.info( | ||
| 314 | + " InstanceService assembled (appliance mode, " | ||
| 315 | + "yuanrong=%s)", | ||
| 316 | + "configured" if yuanrong_client is not None | ||
| 317 | + else "not-configured", | ||
| 318 | + ) | ||
| 319 | + | ||
| 320 | + # NOTE: per-node heartbeat assembly was removed | ||
| 321 | + # the registry no longer receives node heartbeats or derives | ||
| 322 | + # instance status; the gateway polls 元戎 and PATCHes status. | ||
| 323 | + except Exception as exc: | ||
| 324 | + from a2x_registry.register.etcd_client import EtcdError | ||
| 325 | + | ||
| 326 | + if isinstance(exc, EtcdError): | ||
| 327 | + # One-line connection error — no traceback (etcd down / | ||
| 328 | + # unreachable is an ops issue, the message says it all). | ||
| 329 | + logger.error(" etcd backend init failed: %s", exc) | ||
| 330 | + else: | ||
| 331 | + logger.error(" SQL backend init failed: %s", exc, exc_info=True) | ||
| 332 | + raise | ||
| 333 | + | ||
| 43 | # 1. Registry | 334 | # 1. Registry |
| 44 | - _stage("注册服务加载...", 5) | 335 | + _stage("Loading registry services...", 5) |
| 45 | registry_svc = init_registry_service(DATABASE_DIR) | 336 | registry_svc = init_registry_service(DATABASE_DIR) |
| 46 | init_build_service(registry_svc) # share the same instance with build router | 337 | init_build_service(registry_svc) # share the same instance with build router |
| 47 | registry_states = registry_svc.startup() | 338 | registry_states = registry_svc.startup() |
| @@ -174,7 +465,7 @@ def run_warmup() -> None: | |||
| 174 | logger.info("Warmup: registry done (%.1fs)", time.time() - t0) | 465 | logger.info("Warmup: registry done (%.1fs)", time.time() - t0) |
| 175 | 466 | ||
| 176 | # 2. Taxonomy caches | 467 | # 2. Taxonomy caches |
| 177 | - _stage("加载分类树...", 20) | 468 | + _stage("Loading taxonomy tree...", 20) |
| 178 | from a2x_registry.backend.services.taxonomy_service import get_taxonomy_tree | 469 | from a2x_registry.backend.services.taxonomy_service import get_taxonomy_tree |
| 179 | for ds in discover_datasets(): | 470 | for ds in discover_datasets(): |
| 180 | try: | 471 | try: |
| @@ -185,12 +476,12 @@ def run_warmup() -> None: | |||
| 185 | logger.info("Warmup: taxonomy done (%.1fs)", time.time() - t0) | 476 | logger.info("Warmup: taxonomy done (%.1fs)", time.time() - t0) |
| 186 | 477 | ||
| 187 | # 3. A2X engines — pure LLM, runs on the lite install too. | 478 | # 3. A2X engines — pure LLM, runs on the lite install too. |
| 188 | - _stage("加载 A2X 搜索引擎...", 35) | 479 | + _stage("Loading A2X search engine...", 35) |
| 189 | for ds in discover_datasets(): | 480 | for ds in discover_datasets(): |
| 190 | paths = resolve_dataset_paths(ds) | 481 | paths = resolve_dataset_paths(ds) |
| 191 | if paths["taxonomy_path"].exists(): | 482 | if paths["taxonomy_path"].exists(): |
| 192 | for mode in ("get_one", "get_all", "get_important"): | 483 | for mode in ("get_one", "get_all", "get_important"): |
| 193 | - _stage(f"加载 A2X {mode} ({ds})...", 35) | 484 | + _stage(f"Loading A2X {mode} ({ds})...", 35) |
| 194 | try: | 485 | try: |
| 195 | search_service._get_a2x(ds, mode) | 486 | search_service._get_a2x(ds, mode) |
| 196 | logger.info(" A2X %s ready: %s", mode, ds) | 487 | logger.info(" A2X %s ready: %s", mode, ds) |
| @@ -202,7 +493,7 @@ def run_warmup() -> None: | |||
| 202 | # sentence_transformers). On lite installs we skip them cleanly. | 493 | # sentence_transformers). On lite installs we skip them cleanly. |
| 203 | if feature_flags.has("vector"): | 494 | if feature_flags.has("vector"): |
| 204 | # 4. Clean stale ChromaDB collections | 495 | # 4. Clean stale ChromaDB collections |
| 205 | - _stage("清理向量数据库...", 58) | 496 | + _stage("Cleaning vector store...", 58) |
| 206 | try: | 497 | try: |
| 207 | import chromadb | 498 | import chromadb |
| 208 | chroma_dir = str(DATABASE_DIR / "chroma") | 499 | chroma_dir = str(DATABASE_DIR / "chroma") |
| @@ -217,9 +508,9 @@ def run_warmup() -> None: | |||
| 217 | logger.warning(" ChromaDB cleanup failed: %s", e) | 508 | logger.warning(" ChromaDB cleanup failed: %s", e) |
| 218 | 509 | ||
| 219 | # 5. Vector sync for registry-managed datasets | 510 | # 5. Vector sync for registry-managed datasets |
| 220 | - _stage("同步向量数据库...", 62) | 511 | + _stage("Syncing vector store...", 62) |
| 221 | for ds in registry_states: | 512 | for ds in registry_states: |
| 222 | - _stage(f"同步向量数据库 ({ds})...", 62) | 513 | + _stage(f"Syncing vector store ({ds})...", 62) |
| 223 | try: | 514 | try: |
| 224 | search_service.sync_vector(ds) | 515 | search_service.sync_vector(ds) |
| 225 | logger.info(" Vector sync done: %s", ds) | 516 | logger.info(" Vector sync done: %s", ds) |
| @@ -228,9 +519,9 @@ def run_warmup() -> None: | |||
| 228 | logger.info("Warmup: vector sync done (%.1fs)", time.time() - t0) | 519 | logger.info("Warmup: vector sync done (%.1fs)", time.time() - t0) |
| 229 | 520 | ||
| 230 | # 5b. Vector engines | 521 | # 5b. Vector engines |
| 231 | - _stage("加载向量搜索引擎...", 75) | 522 | + _stage("Loading vector search engine...", 75) |
| 232 | for ds in discover_datasets(): | 523 | for ds in discover_datasets(): |
| 233 | - _stage(f"加载向量引擎 ({ds})...", 75) | 524 | + _stage(f"Loading vector engine ({ds})...", 75) |
| 234 | try: | 525 | try: |
| 235 | search_service._get_vector(ds) | 526 | search_service._get_vector(ds) |
| 236 | logger.info(" Vector ready: %s", ds) | 527 | logger.info(" Vector ready: %s", ds) |
| @@ -239,7 +530,7 @@ def run_warmup() -> None: | |||
| 239 | logger.info("Warmup: vector done (%.1fs)", time.time() - t0) | 530 | logger.info("Warmup: vector done (%.1fs)", time.time() - t0) |
| 240 | 531 | ||
| 241 | # 6. Pre-heat embedding models (one per unique model across datasets) | 532 | # 6. Pre-heat embedding models (one per unique model across datasets) |
| 242 | - _stage("预热向量模型...", 90) | 533 | + _stage("Pre-heating embedding model...", 90) |
| 243 | seen_models = set() | 534 | seen_models = set() |
| 244 | for ds in discover_datasets(): | 535 | for ds in discover_datasets(): |
| 245 | model_name = search_service.read_vector_config(ds) | 536 | model_name = search_service.read_vector_config(ds) |
| @@ -254,13 +545,18 @@ def run_warmup() -> None: | |||
| 254 | else: | 545 | else: |
| 255 | logger.info("Warmup: lite install detected — skipping vector / chroma stages") | 546 | logger.info("Warmup: lite install detected — skipping vector / chroma stages") |
| 256 | 547 | ||
| 257 | - warmup_state["stage"] = "完成" | 548 | + warmup_state["stage"] = "complete" |
| 258 | warmup_state["progress"] = 100 | 549 | warmup_state["progress"] = 100 |
| 259 | warmup_state["ready"] = True | 550 | warmup_state["ready"] = True |
| 260 | logger.info("Warmup [100%%] complete — total %.1fs", time.time() - t0) | 551 | logger.info("Warmup [100%%] complete — total %.1fs", time.time() - t0) |
| 261 | 552 | ||
| 262 | except Exception as e: | 553 | except Exception as e: |
| 263 | - import traceback | 554 | + from a2x_registry.register.etcd_client import EtcdError |
| 555 | + | ||
| 264 | warmup_state["error"] = str(e) | 556 | warmup_state["error"] = str(e) |
| 265 | warmup_state["ready"] = True | 557 | warmup_state["ready"] = True |
| 266 | - logger.error("Warmup error: %s\n%s", e, traceback.format_exc()) | 558 | + if isinstance(e, EtcdError): |
| 559 | + logger.error("Warmup error: %s", e) # one-liner, no traceback | ||
| 560 | + else: | ||
| 561 | + import traceback | ||
| 562 | + logger.error("Warmup error: %s\n%s", e, traceback.format_exc()) | ||
| @@ -4,11 +4,13 @@ | |||
| 4 | # - llm_client: LLMClient, LLMResponse, parse_json_response | 4 | # - llm_client: LLMClient, LLMResponse, parse_json_response |
| 5 | # - evaluation: compute_set_metrics | 5 | # - evaluation: compute_set_metrics |
| 6 | # - naming: generate_output_dir | 6 | # - naming: generate_output_dir |
| 7 | +# - log: DailyCompressedFileHandler | ||
| 7 | 8 | ||
| 8 | from .models import SearchResult | 9 | from .models import SearchResult |
| 9 | from .llm_client import LLMClient, LLMResponse, parse_json_response | 10 | from .llm_client import LLMClient, LLMResponse, parse_json_response |
| 10 | from .evaluation import compute_set_metrics | 11 | from .evaluation import compute_set_metrics |
| 11 | from .naming import generate_output_dir | 12 | from .naming import generate_output_dir |
| 13 | +from .log import DailyCompressedFileHandler | ||
| 12 | from .errors import ( | 14 | from .errors import ( |
| 13 | A2XRegistryError, | 15 | A2XRegistryError, |
| 14 | VectorSearchUnavailableError, | 16 | VectorSearchUnavailableError, |
| @@ -22,6 +24,7 @@ __all__ = [ | |||
| 22 | 'LLMClient', 'LLMResponse', 'parse_json_response', | 24 | 'LLMClient', 'LLMResponse', 'parse_json_response', |
| 23 | 'compute_set_metrics', | 25 | 'compute_set_metrics', |
| 24 | 'generate_output_dir', | 26 | 'generate_output_dir', |
| 27 | + 'DailyCompressedFileHandler', | ||
| 25 | 'A2XRegistryError', 'VectorSearchUnavailableError', 'LLMNotConfiguredError', | 28 | 'A2XRegistryError', 'VectorSearchUnavailableError', 'LLMNotConfiguredError', |
| 26 | 'FeatureNotInstalledError', | 29 | 'FeatureNotInstalledError', |
| 27 | 'feature_flags', | 30 | 'feature_flags', |
| @@ -0,0 +1,273 @@ | |||
| 1 | +"""Unified SQL backend: schema source of truth + Backend abstraction. | ||
| 2 | + | ||
| 3 | +Two storage backends share the same schema and parameterized SQL, selectable | ||
| 4 | +via ``connect(cfg)["kind"]``: | ||
| 5 | + | ||
| 6 | +- ``sqlite`` - production single-node, file-persisted (default). | ||
| 7 | +- ``memory`` - debug only, ``sqlite3 ":memory:"``; data lost on process exit. | ||
| 8 | + | ||
| 9 | +Business code depends only on ``Backend.execute / query``, never on the kind. | ||
| 10 | +Switching backends changes only ``connect(cfg)``; callers stay unchanged. | ||
| 11 | +""" | ||
| 12 | + | ||
| 13 | +from __future__ import annotations | ||
| 14 | + | ||
| 15 | +import sqlite3 | ||
| 16 | +from typing import Any | ||
| 17 | + | ||
| 18 | + | ||
| 19 | +# ── schema SQL source of truth ───────────────────────────────── | ||
| 20 | +# Kept in sync with tests/db/schema.sql; the test side imports from here to | ||
| 21 | +# avoid maintaining two copies. | ||
| 22 | + | ||
| 23 | +SCHEMA_SQL = """\ | ||
| 24 | +-- Agent OS registry table schema (authoritative) | ||
| 25 | +-- Use CREATE TABLE/INDEX IF NOT EXISTS so startup-time creation is idempotent. | ||
| 26 | + | ||
| 27 | +-- Registry meta: which named registries exist, their kind, and config | ||
| 28 | +CREATE TABLE IF NOT EXISTS registry_meta ( | ||
| 29 | + registry TEXT PRIMARY KEY, -- 'toolret'/'publicmcp'/'default'/'image-registry'/'instance-registry' | ||
| 30 | + kind TEXT NOT NULL, -- service | image | instance | ||
| 31 | + config TEXT -- JSON: service-kind stores register_config/vector_config/taxonomy_hash | ||
| 32 | +); | ||
| 33 | + | ||
| 34 | +-- Service (A2X: generic/a2a/skill) -- discovery / classification rely on it | ||
| 35 | +CREATE TABLE IF NOT EXISTS service ( | ||
| 36 | + registry TEXT NOT NULL, | ||
| 37 | + service_id TEXT NOT NULL, | ||
| 38 | + type TEXT NOT NULL, -- generic | a2a | skill | ||
| 39 | + source TEXT NOT NULL, -- user_config | api_config | ephemeral | skill_folder | ||
| 40 | + name TEXT, -- hot: classification LLM input / filter | ||
| 41 | + description TEXT, -- hot: classification LLM input | ||
| 42 | + data TEXT NOT NULL, -- JSON: service_data / agent_card / skill_data | ||
| 43 | + created_at TEXT NOT NULL, | ||
| 44 | + updated_at TEXT NOT NULL, | ||
| 45 | + PRIMARY KEY (registry, service_id) | ||
| 46 | +); | ||
| 47 | +CREATE INDEX IF NOT EXISTS idx_service_type ON service(registry, type); | ||
| 48 | + | ||
| 49 | +-- Image (one row per version: name 主键, framework 降级为展示列) | ||
| 50 | +CREATE TABLE IF NOT EXISTS image ( | ||
| 51 | + registry TEXT NOT NULL, | ||
| 52 | + service_id TEXT NOT NULL, -- image_sid(name, version) | ||
| 53 | + name TEXT NOT NULL, -- hot: 镜像主键(取代原 framework 定位) | ||
| 54 | + framework TEXT, -- 展示字段(非主键),可按其筛选 | ||
| 55 | + version TEXT NOT NULL, -- hot: lookup by version(原 framework_version 更名) | ||
| 56 | + version_key TEXT NOT NULL, -- sort: normalized semver key computed at registration (see image/version_key.py) | ||
| 57 | + is_default INTEGER NOT NULL DEFAULT 0, -- default-version flag for a name (exactly one row per name = 1); not part of sort order | ||
| 58 | + uploaded_by TEXT, -- hot: filter by uploader; pre-seeded entries are 'system' | ||
| 59 | + data TEXT NOT NULL, -- JSON flat (no rootfs wrapper): {runtime_spec, access_mode, env_vars, workspace, mounts, description, package_path, image_archive_path, image_module_version, created_at} | ||
| 60 | + PRIMARY KEY (registry, service_id) | ||
| 61 | +); | ||
| 62 | +CREATE INDEX IF NOT EXISTS idx_image_name ON image(registry, name); | ||
| 63 | +CREATE INDEX IF NOT EXISTS idx_image_name_ver ON image(registry, name, version); | ||
| 64 | +CREATE INDEX IF NOT EXISTS idx_image_by ON image(registry, uploaded_by); | ||
| 65 | +CREATE INDEX IF NOT EXISTS idx_image_order ON image(registry, name, version_key DESC); | ||
| 66 | + | ||
| 67 | +-- Instance (status persisted inside data JSON, written by gateway via PATCH) | ||
| 68 | +CREATE TABLE IF NOT EXISTS instance ( | ||
| 69 | + registry TEXT NOT NULL, | ||
| 70 | + service_id TEXT NOT NULL, -- instance_sid(user, framework) | ||
| 71 | + kind TEXT NOT NULL, -- third-party | jiuwen | ||
| 72 | + framework TEXT, | ||
| 73 | + framework_version TEXT, | ||
| 74 | + node TEXT, -- hot: bulk eviction by node / lookup by node | ||
| 75 | + "user" TEXT, -- hot: lookup a user's instances by user id | ||
| 76 | + data TEXT NOT NULL, -- JSON {address, created_at, last_active_at} | ||
| 77 | + PRIMARY KEY (registry, service_id) | ||
| 78 | +); | ||
| 79 | +CREATE INDEX IF NOT EXISTS idx_instance_node ON instance(registry, node); | ||
| 80 | +CREATE INDEX IF NOT EXISTS idx_instance_fw ON instance(registry, framework, framework_version); | ||
| 81 | +CREATE INDEX IF NOT EXISTS idx_instance_user ON instance(registry, "user"); | ||
| 82 | +CREATE INDEX IF NOT EXISTS idx_instance_order ON instance(registry, framework, "user", service_id); | ||
| 83 | +""" | ||
| 84 | + | ||
| 85 | + | ||
| 86 | +def init_schema(conn: Any) -> None: | ||
| 87 | + """Execute SCHEMA_SQL on the given sqlite3 connection. | ||
| 88 | + | ||
| 89 | + Creates the 4 tables + 9 indexes, idempotent (every statement is | ||
| 90 | + ``CREATE ... IF NOT EXISTS``; re-running neither raises nor alters | ||
| 91 | + existing structures). Called once by ``backend/startup.py`` at startup; | ||
| 92 | + works identically for file-backed and ``:memory:`` connections. | ||
| 93 | + | ||
| 94 | + A legacy image table (framework-keyed) is migrated | ||
| 95 | + first: name=framework / version=framework_version backfill in a | ||
| 96 | + rebuild (SQLite cannot ALTER COLUMN), preserving every row's | ||
| 97 | + service_id / is_default / data. | ||
| 98 | + """ | ||
| 99 | + _migrate_legacy_image_table(conn) | ||
| 100 | + conn.executescript(SCHEMA_SQL) | ||
| 101 | + conn.commit() | ||
| 102 | + | ||
| 103 | + | ||
| 104 | +def _migrate_legacy_image_table(conn: Any) -> None: | ||
| 105 | + """Migrate a framework-keyed image table to the name-keyed layout. | ||
| 106 | + | ||
| 107 | + Detection: an existing ``image`` table that has ``framework_version`` | ||
| 108 | + but no ``name`` column. The rebuild copies each row with | ||
| 109 | + ``name=framework`` / ``version=framework_version`` — same values the | ||
| 110 | + old positioning used, so ``service_id`` (``image_sid`` over the same | ||
| 111 | + two strings) stays valid. Fresh databases and already-migrated ones | ||
| 112 | + are left untouched. Must run **before** ``SCHEMA_SQL`` (its new | ||
| 113 | + indexes reference the ``name``/``version`` columns). | ||
| 114 | + | ||
| 115 | + Interrupted-run recovery, a previously crashed run may | ||
| 116 | + have left the ``image_migrated`` temp table behind — any leftover temp | ||
| 117 | + is resolved **before** migrating: | ||
| 118 | + | ||
| 119 | + - ``image`` table present → the temp is debris from an aborted run and | ||
| 120 | + the surviving original table is authoritative: the temp is dropped | ||
| 121 | + first (otherwise ``CREATE TABLE image_migrated`` collides with it | ||
| 122 | + and startup dies); | ||
| 123 | + - ``image`` table absent → the run died between DROP and RENAME and the | ||
| 124 | + data lives only in the temp: a temp carrying the new (name/version) | ||
| 125 | + layout is renamed into place (zero data loss); an unrecognisable | ||
| 126 | + temp is dropped as garbage. | ||
| 127 | + """ | ||
| 128 | + cols = { | ||
| 129 | + row[1] for row in conn.execute("PRAGMA table_info(image)").fetchall() | ||
| 130 | + } | ||
| 131 | + temp_cols = { | ||
| 132 | + row[1] for row in conn.execute("PRAGMA table_info(image_migrated)").fetchall() | ||
| 133 | + } | ||
| 134 | + | ||
| 135 | + if not cols: | ||
| 136 | + # No image table: fresh database, or a migration interrupted after | ||
| 137 | + # DROP with the data stranded in the temp table. | ||
| 138 | + if {"name", "version"} <= temp_cols: | ||
| 139 | + conn.executescript( | ||
| 140 | + """ | ||
| 141 | + BEGIN; | ||
| 142 | + ALTER TABLE image_migrated RENAME TO image; | ||
| 143 | + COMMIT; | ||
| 144 | + """ | ||
| 145 | + ) | ||
| 146 | + elif temp_cols: | ||
| 147 | + conn.executescript( | ||
| 148 | + "BEGIN; DROP TABLE image_migrated; COMMIT;" | ||
| 149 | + ) | ||
| 150 | + # fresh / recovered / cleaned — SCHEMA_SQL builds the rest | ||
| 151 | + return | ||
| 152 | + | ||
| 153 | + if temp_cols: | ||
| 154 | + # Original table survived: a leftover temp is stale debris (its | ||
| 155 | + # partial copy must NOT win). Drop it so the rebuild below cannot | ||
| 156 | + # collide with CREATE TABLE image_migrated. | ||
| 157 | + conn.executescript( | ||
| 158 | + "BEGIN; DROP TABLE image_migrated; COMMIT;" | ||
| 159 | + ) | ||
| 160 | + | ||
| 161 | + if "name" in cols: | ||
| 162 | + return # already migrated | ||
| 163 | + conn.executescript( | ||
| 164 | + """ | ||
| 165 | + BEGIN; | ||
| 166 | + CREATE TABLE image_migrated ( | ||
| 167 | + registry TEXT NOT NULL, | ||
| 168 | + service_id TEXT NOT NULL, | ||
| 169 | + name TEXT NOT NULL, | ||
| 170 | + framework TEXT, | ||
| 171 | + version TEXT NOT NULL, | ||
| 172 | + version_key TEXT NOT NULL, | ||
| 173 | + is_default INTEGER NOT NULL DEFAULT 0, | ||
| 174 | + uploaded_by TEXT, | ||
| 175 | + data TEXT NOT NULL, | ||
| 176 | + PRIMARY KEY (registry, service_id) | ||
| 177 | + ); | ||
| 178 | + INSERT INTO image_migrated | ||
| 179 | + (registry, service_id, name, framework, version, | ||
| 180 | + version_key, is_default, uploaded_by, data) | ||
| 181 | + SELECT registry, service_id, framework, framework, | ||
| 182 | + framework_version, version_key, is_default, | ||
| 183 | + uploaded_by, data | ||
| 184 | + FROM image; | ||
| 185 | + DROP TABLE image; | ||
| 186 | + ALTER TABLE image_migrated RENAME TO image; | ||
| 187 | + COMMIT; | ||
| 188 | + """ | ||
| 189 | + ) | ||
| 190 | + | ||
| 191 | + | ||
| 192 | +# ── Backend abstraction ──────────────────────────────────────── | ||
| 193 | +# Both backends share the same ``Backend.execute / query`` contract. | ||
| 194 | +# Callers rely on this abstraction to hide file-persisted sqlite vs | ||
| 195 | +# in-memory debug differences. | ||
| 196 | + | ||
| 197 | +_KIND_SQLITE = "sqlite" | ||
| 198 | +_KIND_MEMORY = "memory" | ||
| 199 | + | ||
| 200 | + | ||
| 201 | +class Backend: | ||
| 202 | + """Storage backend abstraction. | ||
| 203 | + | ||
| 204 | + - ``execute(sql, args)``: write-transaction semantics. The statement is | ||
| 205 | + wrapped in ``with conn`` -- success commits, an exception rolls back | ||
| 206 | + that statement. | ||
| 207 | + - ``query(sql, args)``: read semantics. Returns ``list[dict]`` with | ||
| 208 | + column names as keys; empty result returns ``[]``. | ||
| 209 | + | ||
| 210 | + All SQL inputs must be parameterized (``?`` placeholders + | ||
| 211 | + ``args: tuple``); string-concatenating values is forbidden. | ||
| 212 | + """ | ||
| 213 | + | ||
| 214 | + __slots__ = ("kind", "conn") | ||
| 215 | + | ||
| 216 | + def __init__(self, kind: str, conn: Any) -> None: | ||
| 217 | + self.kind = kind | ||
| 218 | + self.conn = conn | ||
| 219 | + | ||
| 220 | + def execute(self, sql: str, args: tuple = ()) -> None: | ||
| 221 | + """Execute a single write SQL statement. | ||
| 222 | + | ||
| 223 | + Wraps the statement in ``with conn`` so it becomes its own | ||
| 224 | + transaction (commit on success / rollback on exception). | ||
| 225 | + """ | ||
| 226 | + with self.conn: # commit on success / rollback on exception | ||
| 227 | + self.conn.execute(sql, args) | ||
| 228 | + | ||
| 229 | + def query(self, sql: str, args: tuple = ()) -> list[dict]: | ||
| 230 | + """Read query, returns list[dict] (column names as keys, empty result []). | ||
| 231 | + | ||
| 232 | + ``row_factory`` is set to ``sqlite3.Row`` in ``connect``; rows are | ||
| 233 | + converted to dicts here. | ||
| 234 | + """ | ||
| 235 | + cur = self.conn.execute(sql, args) | ||
| 236 | + rows = cur.fetchall() | ||
| 237 | + return [{k: row[k] for k in row.keys()} for row in rows] | ||
| 238 | + | ||
| 239 | + | ||
| 240 | +def connect(cfg: dict) -> Backend: | ||
| 241 | + """Return a Backend according to the config. | ||
| 242 | + | ||
| 243 | + - ``{"kind": "sqlite", "path": "<db file>"}``: returns | ||
| 244 | + ``Backend(kind="sqlite", conn=sqlite3.Connection)``; the connection sets | ||
| 245 | + ``row_factory=sqlite3.Row`` for convenient column-name access. | ||
| 246 | + - ``{"kind": "memory"}``: returns | ||
| 247 | + ``Backend(kind="memory", conn=sqlite3.Connection)`` backed by | ||
| 248 | + ``sqlite3.connect(":memory:")``. Debug only - data is lost when the | ||
| 249 | + process exits. ``check_same_thread=False`` so FastAPI sync routes | ||
| 250 | + running in a threadpool can share the same in-memory connection. | ||
| 251 | + - Any other kind: ``ValueError``. | ||
| 252 | + """ | ||
| 253 | + kind = cfg.get("kind") | ||
| 254 | + if kind == _KIND_SQLITE: | ||
| 255 | + path = cfg.get("path") | ||
| 256 | + if not path: | ||
| 257 | + raise ValueError("sqlite backend requires cfg['path']") | ||
| 258 | + # check_same_thread=False: FastAPI runs sync routes in a threadpool; | ||
| 259 | + # the connection is created in the warmup thread and reused by | ||
| 260 | + # worker threads. SQLite-level concurrency is serialized via the | ||
| 261 | + # GIL + the default busy_timeout; cross-thread sharing is safe as | ||
| 262 | + # long as we don't concurrently mutate (the registry's CRUD is | ||
| 263 | + # short-lived and the sweeper is the only background writer). | ||
| 264 | + conn = sqlite3.connect(path, check_same_thread=False) | ||
| 265 | + conn.row_factory = sqlite3.Row | ||
| 266 | + return Backend(kind=_KIND_SQLITE, conn=conn) | ||
| 267 | + if kind == _KIND_MEMORY: | ||
| 268 | + # check_same_thread=False: FastAPI runs sync routes in a threadpool; | ||
| 269 | + # the in-memory connection must be shareable across those threads. | ||
| 270 | + conn = sqlite3.connect(":memory:", check_same_thread=False) | ||
| 271 | + conn.row_factory = sqlite3.Row | ||
| 272 | + return Backend(kind=_KIND_MEMORY, conn=conn) | ||
| 273 | + raise ValueError(f"unknown backend kind: {kind!r}") | ||
| @@ -0,0 +1,56 @@ | |||
| 1 | +"""Deterministic ID + timestamp helpers for the registry. | ||
| 2 | + | ||
| 3 | +- now_iso(): UTC ISO8601 timestamp (second precision, 'Z' suffix). | ||
| 4 | +- image_sid(name, version): deterministic service_id for an image row — | ||
| 5 | + "image_" + sha256(name|version)[:16](name 主键). | ||
| 6 | +- instance_sid(user, framework): deterministic service_id for an instance | ||
| 7 | + row — "generic_" + sha256(user|framework)[:8]. | ||
| 8 | + | ||
| 9 | +These helpers are pure functions (no I/O, no globals) so they can be reused | ||
| 10 | +by the image / instance modules and by tests without a backend. | ||
| 11 | +""" | ||
| 12 | + | ||
| 13 | +from __future__ import annotations | ||
| 14 | + | ||
| 15 | +import hashlib | ||
| 16 | +from datetime import datetime, timezone | ||
| 17 | + | ||
| 18 | + | ||
| 19 | +def now_iso() -> str: | ||
| 20 | + """Return current UTC time as an ISO8601 string with a 'Z' suffix. | ||
| 21 | + | ||
| 22 | + Second precision is sufficient for registry timestamps (created_at / | ||
| 23 | + updated_at). The fixed format guarantees lexicographic sortability. | ||
| 24 | + """ | ||
| 25 | + return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") | ||
| 26 | + | ||
| 27 | + | ||
| 28 | +def image_sid(name: str, version: str) -> str: | ||
| 29 | + """Return the deterministic service_id for an image row. | ||
| 30 | + | ||
| 31 | + Formula: "image_" + sha256(name + "|" + version)[:16]. | ||
| 32 | + The same (name, version) always yields the same id, so a repeated | ||
| 33 | + register upserts the existing row instead of creating a duplicate. | ||
| 34 | + Legacy rows keyed by (framework, framework_version) keep their ids | ||
| 35 | + valid after the §6 migration because name=framework / version= | ||
| 36 | + framework_version were backfilled with the same two strings. | ||
| 37 | + | ||
| 38 | + ``name`` must not contain ``|`` (enforced at the API boundary) so the | ||
| 39 | + encoding stays injective: ("a|b", "c") and ("a", "b|c") would otherwise | ||
| 40 | + hash to the same id and silently overwrite each other. | ||
| 41 | + """ | ||
| 42 | + raw = f"{name}|{version}" | ||
| 43 | + digest = hashlib.sha256(raw.encode("utf-8")).hexdigest() | ||
| 44 | + return "image_" + digest[:16] | ||
| 45 | + | ||
| 46 | + | ||
| 47 | +def instance_sid(user: str, framework: str) -> str: | ||
| 48 | + """Return the deterministic service_id for an instance row. | ||
| 49 | + | ||
| 50 | + Formula: "generic_" + sha256(user + "|" + framework)[:8]. The same | ||
| 51 | + (user, framework) always yields the same id, guaranteeing one row per | ||
| 52 | + (user, framework) pair (single-instance-per-user-per-framework). | ||
| 53 | + """ | ||
| 54 | + raw = f"{user}|{framework}" | ||
| 55 | + digest = hashlib.sha256(raw.encode("utf-8")).hexdigest() | ||
| 56 | + return "generic_" + digest[:8] | ||
| @@ -0,0 +1,96 @@ | |||
| 1 | +"""Daily-rotating, gzip-compressed file log handler for the registry backend.""" | ||
| 2 | + | ||
| 3 | +from __future__ import annotations | ||
| 4 | + | ||
| 5 | +import gzip | ||
| 6 | +import logging | ||
| 7 | +import logging.handlers | ||
| 8 | +import shutil | ||
| 9 | +import time | ||
| 10 | +from datetime import date | ||
| 11 | +from pathlib import Path | ||
| 12 | + | ||
| 13 | +logger = logging.getLogger(__name__) | ||
| 14 | + | ||
| 15 | + | ||
| 16 | +class DailyCompressedFileHandler(logging.handlers.TimedRotatingFileHandler): | ||
| 17 | + """Daily-rotating, gzip-compressed log handler with a fixed current name. | ||
| 18 | + | ||
| 19 | + Current day: a2x-registry.log (fixed name, no date) | ||
| 20 | + Previous days: a2x-registry-2026-08-11.log.gz (date-stamped, compressed) | ||
| 21 | + At each midnight rollover the finished day's file is gzipped under the | ||
| 22 | + date it was written, a fresh fixed-name file is opened, and the oldest | ||
| 23 | + ``.gz`` files beyond ``retention_days`` are pruned. A fixed-name file | ||
| 24 | + left over from a previous day (service down across midnight) is | ||
| 25 | + archived on startup based on its mtime. | ||
| 26 | + """ | ||
| 27 | + | ||
| 28 | + def __init__(self, log_dir: Path, stem: str, retention_days: int) -> None: | ||
| 29 | + self._log_dir = Path(log_dir) | ||
| 30 | + self._stem = stem | ||
| 31 | + self._retention_days = retention_days | ||
| 32 | + self._current_day = date.today() | ||
| 33 | + super().__init__( | ||
| 34 | + self._log_dir / self._fixed_name(), | ||
| 35 | + when="midnight", | ||
| 36 | + interval=1, | ||
| 37 | + backupCount=retention_days, | ||
| 38 | + encoding="utf-8", | ||
| 39 | + delay=True, | ||
| 40 | + ) | ||
| 41 | + self._archive_stale_file() | ||
| 42 | + | ||
| 43 | + def _fixed_name(self) -> str: | ||
| 44 | + return f"{self._stem}.log" | ||
| 45 | + | ||
| 46 | + def _archived_name(self, day: date) -> str: | ||
| 47 | + return f"{self._stem}-{day:%Y-%m-%d}.log.gz" | ||
| 48 | + | ||
| 49 | + def _archive(self, src: Path, day: date) -> None: | ||
| 50 | + gz_path = self._log_dir / self._archived_name(day) | ||
| 51 | + with open(src, "rb") as f_in, gzip.open(gz_path, "wb") as f_out: | ||
| 52 | + shutil.copyfileobj(f_in, f_out) | ||
| 53 | + src.unlink() | ||
| 54 | + | ||
| 55 | + def _archive_stale_file(self) -> None: | ||
| 56 | + """启动时归档跨天残留的固定名日志(服务停跨天后重启的场景)。""" | ||
| 57 | + cur = self._log_dir / self._fixed_name() | ||
| 58 | + try: | ||
| 59 | + if cur.exists(): | ||
| 60 | + mtime_day = date.fromtimestamp(cur.stat().st_mtime) | ||
| 61 | + if mtime_day != self._current_day: | ||
| 62 | + self._archive(cur, mtime_day) | ||
| 63 | + self._prune() | ||
| 64 | + except OSError as exc: | ||
| 65 | + # 归档失败时保留原日志文件(不删除,避免数据丢失),只记录问题。 | ||
| 66 | + logger.exception("Failed to archive stale log %s: %s", cur, exc) | ||
| 67 | + | ||
| 68 | + def doRollover(self) -> None: | ||
| 69 | + if self.stream: | ||
| 70 | + self.stream.close() | ||
| 71 | + self.stream = None | ||
| 72 | + cur = Path(self.baseFilename) | ||
| 73 | + try: | ||
| 74 | + if cur.exists(): | ||
| 75 | + self._archive(cur, self._current_day) | ||
| 76 | + except OSError as exc: | ||
| 77 | + # 压缩/删除失败时保留原日志文件(不删除,避免数据丢失),只记录问题。 | ||
| 78 | + logger.exception("Failed to gzip rotated log %s: %s", cur, exc) | ||
| 79 | + finally: | ||
| 80 | + # 无论压缩是否成功,都重开固定名文件并恢复可写流 | ||
| 81 | + self._current_day = date.today() | ||
| 82 | + self.baseFilename = str(self._log_dir / self._fixed_name()) | ||
| 83 | + self.stream = self._open() | ||
| 84 | + self._prune() | ||
| 85 | + self.rolloverAt = self.computeRollover(time.time()) | ||
| 86 | + | ||
| 87 | + def _prune(self) -> None: | ||
| 88 | + files = sorted( | ||
| 89 | + self._log_dir.glob(f"{self._stem}-*.log.gz"), | ||
| 90 | + key=lambda p: p.name, | ||
| 91 | + ) | ||
| 92 | + for old in files[: max(0, len(files) - self._retention_days)]: | ||
| 93 | + try: | ||
| 94 | + old.unlink() | ||
| 95 | + except OSError: | ||
| 96 | + pass | ||
| @@ -20,6 +20,11 @@ The store / models / sweeper layer is FastAPI-free (testable without uvicorn). | |||
| 20 | Web concerns live in ``deps.py`` / ``router.py``. The ``system_ctx`` module | 20 | Web concerns live in ``deps.py`` / ``router.py``. The ``system_ctx`` module |
| 21 | provides the synthetic ``AuthContext`` the sweeper uses to call into | 21 | provides the synthetic ``AuthContext`` the sweeper uses to call into |
| 22 | ``RegistryService.deregister`` for hard-deletion. | 22 | ``RegistryService.deregister`` for hard-deletion. |
| 23 | + | ||
| 24 | +NOTE: the appliance-mode per-node heartbeat (``NodeHeartbeatStore`` / | ||
| 25 | +``HeartbeatManager`` / ``NodeHeartbeatSweeper``, ``/api/nodes/{node}/heartbeat`` | ||
| 26 | +and ``GET/POST /api/lease-config``) was removed — instance | ||
| 27 | +liveness is now reported by the gateway via ``PATCH /api/instances``. | ||
| 23 | """ | 28 | """ |
| 24 | 29 | ||
| 25 | from .errors import ( | 30 | from .errors import ( |
| @@ -30,7 +35,10 @@ from .errors import ( | |||
| 30 | from .models import HeartbeatLease, HBState | 35 | from .models import HeartbeatLease, HBState |
| 31 | from .store import HeartbeatStore | 36 | from .store import HeartbeatStore |
| 32 | from .sweeper import HeartbeatSweeper | 37 | from .sweeper import HeartbeatSweeper |
| 33 | -from .deps import get_heartbeat_store, set_heartbeat_store | 38 | +from .deps import ( |
| 39 | + get_heartbeat_store, | ||
| 40 | + set_heartbeat_store, | ||
| 41 | +) | ||
| 34 | from .system_ctx import SYSTEM_CTX | 42 | from .system_ctx import SYSTEM_CTX |
| 35 | 43 | ||
| 36 | __all__ = [ | 44 | __all__ = [ |
| @@ -1,18 +1,24 @@ | |||
| 1 | """Module-level HeartbeatStore singleton + FastAPI dep helpers. | 1 | """Module-level HeartbeatStore singleton + FastAPI dep helpers. |
| 2 | 2 | ||
| 3 | -Mirrors ``a2x_registry.auth.deps`` shape exactly — single global, set | 3 | +Mirrors ``a2x_registry.auth.deps`` shape exactly - single global, set |
| 4 | once at backend startup, returned by ``get_heartbeat_store()``. The | 4 | once at backend startup, returned by ``get_heartbeat_store()``. The |
| 5 | -``None`` return path means "heartbeat module not initialized" — routers | 5 | +``None`` return path means "heartbeat module not initialized" - routers |
| 6 | should fall back to permanent-service behavior in that case (matches | 6 | should fall back to permanent-service behavior in that case (matches |
| 7 | -the auth module's ``store is None → anon`` fallback). | 7 | +the auth module's ``store is None -> anon`` fallback). |
| 8 | + | ||
| 9 | +NOTE: the per-node ``HeartbeatManager`` singleton was removed together | ||
| 10 | +with the appliance-mode node heartbeat endpoints. | ||
| 8 | """ | 11 | """ |
| 9 | 12 | ||
| 10 | from __future__ import annotations | 13 | from __future__ import annotations |
| 11 | 14 | ||
| 15 | +import logging | ||
| 12 | from typing import Optional | 16 | from typing import Optional |
| 13 | 17 | ||
| 14 | from .store import HeartbeatStore | 18 | from .store import HeartbeatStore |
| 15 | 19 | ||
| 20 | +logger = logging.getLogger(__name__) | ||
| 21 | + | ||
| 16 | _store: Optional[HeartbeatStore] = None | 22 | _store: Optional[HeartbeatStore] = None |
| 17 | 23 | ||
| 18 | 24 | ||
| @@ -12,6 +12,9 @@ Persisted state (``RegistryEntry.lease_ttl``) lives in the register | |||
| 12 | module; the table only holds the **runtime** countdown state. Restart | 12 | module; the table only holds the **runtime** countdown state. Restart |
| 13 | clears it; the store re-grants a grace-period lease for every entry whose | 13 | clears it; the store re-grants a grace-period lease for every entry whose |
| 14 | persisted ``lease_ttl`` is non-empty (restart recovery). | 14 | persisted ``lease_ttl`` is non-empty (restart recovery). |
| 15 | + | ||
| 16 | +NOTE: ``NodeLeaseConfig`` (per-node lease configuration, appliance mode) | ||
| 17 | +was removed together with the node heartbeat endpoints. | ||
| 15 | """ | 18 | """ |
| 16 | 19 | ||
| 17 | from __future__ import annotations | 20 | from __future__ import annotations |
| @@ -4,23 +4,30 @@ Mounted at app level (no prefix beyond the dataset path). Routes: | |||
| 4 | 4 | ||
| 5 | POST /api/datasets/{ds}/services/{sid}/heartbeat | 5 | POST /api/datasets/{ds}/services/{sid}/heartbeat |
| 6 | body: {status?: "online"|"busy"|"offline"} | 6 | body: {status?: "online"|"busy"|"offline"} |
| 7 | - → 200 {service_id, expires_at, state} | 7 | + -> 200 {service_id, expires_at, state} |
| 8 | - → 404 if no lease (service permanent / never registered with ttl) | 8 | + -> 404 if no lease (service permanent / never registered with ttl) |
| 9 | 9 | ||
| 10 | DELETE /api/datasets/{ds}/services/{sid}/heartbeat | 10 | DELETE /api/datasets/{ds}/services/{sid}/heartbeat |
| 11 | body: {permanent?: bool = false} | 11 | body: {permanent?: bool = false} |
| 12 | - → 200 {service_id, deleted: bool} | 12 | + -> 200 {service_id, deleted: bool} |
| 13 | permanent=false: mark unhealthy, grace window starts | 13 | permanent=false: mark unhealthy, grace window starts |
| 14 | permanent=true: hard-delete via RegistryService (same path as | 14 | permanent=true: hard-delete via RegistryService (same path as |
| 15 | an admin DELETE /services/{sid}) | 15 | an admin DELETE /services/{sid}) |
| 16 | 16 | ||
| 17 | Both endpoints respect ``Depends(authorize)`` for namespace + auth | 17 | Both endpoints respect ``Depends(authorize)`` for namespace + auth |
| 18 | checks (mirrors the existing reservation endpoints in dataset.py). | 18 | checks (mirrors the existing reservation endpoints in dataset.py). |
| 19 | + | ||
| 20 | +NOTE: the appliance-mode per-node heartbeat endpoints | ||
| 21 | +(``POST /api/nodes/{node}/heartbeat``, ``GET/POST /api/lease-config``) | ||
| 22 | +were removed — the registry no longer receives node | ||
| 23 | +heartbeats; instance liveness is reported by the gateway via | ||
| 24 | +``PATCH /api/instances/{service_id}`` (据元戎 List). | ||
| 19 | """ | 25 | """ |
| 20 | 26 | ||
| 21 | from __future__ import annotations | 27 | from __future__ import annotations |
| 22 | 28 | ||
| 23 | import logging | 29 | import logging |
| 30 | +import time as _t | ||
| 24 | from typing import Optional | 31 | from typing import Optional |
| 25 | 32 | ||
| 26 | from fastapi import APIRouter, Depends, HTTPException | 33 | from fastapi import APIRouter, Depends, HTTPException |
| @@ -100,7 +107,6 @@ async def send_heartbeat( | |||
| 100 | dataset, service_id, exc, | 107 | dataset, service_id, exc, |
| 101 | ) | 108 | ) |
| 102 | 109 | ||
| 103 | - import time as _t | ||
| 104 | return { | 110 | return { |
| 105 | "service_id": service_id, | 111 | "service_id": service_id, |
| 106 | "dataset": dataset, | 112 | "dataset": dataset, |
| @@ -1,4 +1,4 @@ | |||
| 1 | -"""HeartbeatStore — per-namespace lease tracking on top of the shared | 1 | +"""HeartbeatStore - per-namespace lease tracking on top of the shared |
| 2 | ``LeaseTable`` state machine. | 2 | ``LeaseTable`` state machine. |
| 3 | 3 | ||
| 4 | Pure runtime store: no disk I/O, no FastAPI. The corresponding persisted | 4 | Pure runtime store: no disk I/O, no FastAPI. The corresponding persisted |
| @@ -7,10 +7,14 @@ is wired into ``RegistryService`` via the ``set_unhealthy_check`` callback | |||
| 7 | at backend startup; the sweeper invokes ``RegistryService.deregister`` | 7 | at backend startup; the sweeper invokes ``RegistryService.deregister`` |
| 8 | through the synthetic ``SYSTEM_CTX`` for hard deletion. | 8 | through the synthetic ``SYSTEM_CTX`` for hard deletion. |
| 9 | 9 | ||
| 10 | -This module owns the heartbeat-specific concerns — the per-namespace | 10 | +This module owns the heartbeat-specific concerns - the per-namespace |
| 11 | -4-corner validation matrix and the ``(dataset, service_id)`` keying — | 11 | +4-corner validation matrix and the ``(dataset, service_id)`` keying - |
| 12 | and delegates the actual lease countdown / state transitions to | 12 | and delegates the actual lease countdown / state transitions to |
| 13 | ``a2x_registry.common.lease.LeaseTable``. | 13 | ``a2x_registry.common.lease.LeaseTable``. |
| 14 | + | ||
| 15 | +NOTE: ``NodeHeartbeatStore`` (appliance-mode per-node variant) was | ||
| 16 | +removed together with the node heartbeat endpoints — | ||
| 17 | +instance liveness is now reported by the gateway via PATCH status. | ||
| 14 | """ | 18 | """ |
| 15 | 19 | ||
| 16 | from __future__ import annotations | 20 | from __future__ import annotations |
| @@ -18,7 +22,7 @@ from __future__ import annotations | |||
| 18 | import logging | 22 | import logging |
| 19 | from typing import List, Optional, Tuple | 23 | from typing import List, Optional, Tuple |
| 20 | 24 | ||
| 21 | -from a2x_registry.common.lease import LeaseTable | 25 | +from a2x_registry.common.lease import Lease, LeaseState, LeaseTable |
| 22 | 26 | ||
| 23 | from .errors import ( | 27 | from .errors import ( |
| 24 | HeartbeatNotSupportedError, | 28 | HeartbeatNotSupportedError, |
| @@ -30,7 +34,7 @@ from .models import HeartbeatLease | |||
| 30 | logger = logging.getLogger(__name__) | 34 | logger = logging.getLogger(__name__) |
| 31 | 35 | ||
| 32 | 36 | ||
| 33 | -# (dataset, service_id) → HeartbeatLease | 37 | +# (dataset, service_id) -> HeartbeatLease |
| 34 | _LeaseKey = Tuple[str, str] | 38 | _LeaseKey = Tuple[str, str] |
| 35 | 39 | ||
| 36 | 40 | ||
| @@ -1,15 +1,18 @@ | |||
| 1 | -"""HeartbeatSweeper — background daemon that drives state transitions. | 1 | +"""HeartbeatSweeper - background daemon that drives state transitions. |
| 2 | 2 | ||
| 3 | Single daemon thread, period configurable (default 5s). Each tick calls | 3 | Single daemon thread, period configurable (default 5s). Each tick calls |
| 4 | ``HeartbeatStore.sweep_tick()`` to get the lists of newly-unhealthy and | 4 | ``HeartbeatStore.sweep_tick()`` to get the lists of newly-unhealthy and |
| 5 | to-hard-delete sids, then invokes ``RegistryService.deregister`` for the | 5 | to-hard-delete sids, then invokes ``RegistryService.deregister`` for the |
| 6 | -latter (using the synthetic ``SYSTEM_CTX`` — same code path as | 6 | +latter (using the synthetic ``SYSTEM_CTX`` - same code path as |
| 7 | admin-initiated DELETE, so cache invalidation / file rewrite / vector | 7 | admin-initiated DELETE, so cache invalidation / file rewrite / vector |
| 8 | sync all fire as expected). | 8 | sync all fire as expected). |
| 9 | 9 | ||
| 10 | Tests can either drive ``store.sweep_tick`` directly (synchronous, | 10 | Tests can either drive ``store.sweep_tick`` directly (synchronous, |
| 11 | -millisecond-fast — preferred) or spin a sweeper with a short period. | 11 | +millisecond-fast - preferred) or spin a sweeper with a short period. |
| 12 | ``sweep_once()`` is exposed for the direct-drive case. | 12 | ``sweep_once()`` is exposed for the direct-drive case. |
| 13 | + | ||
| 14 | +NOTE: ``NodeHeartbeatSweeper`` (appliance-mode per-node variant) was | ||
| 15 | +removed together with the node heartbeat endpoints. | ||
| 13 | """ | 16 | """ |
| 14 | 17 | ||
| 15 | from __future__ import annotations | 18 | from __future__ import annotations |
| @@ -17,9 +20,9 @@ from __future__ import annotations | |||
| 17 | import logging | 20 | import logging |
| 18 | import threading | 21 | import threading |
| 19 | import time | 22 | import time |
| 20 | -from typing import TYPE_CHECKING | 23 | +from typing import TYPE_CHECKING, Optional |
| 21 | 24 | ||
| 22 | -from .errors import HeartbeatError # noqa: F401 — re-exported via __init__ | 25 | +from .errors import HeartbeatError # noqa: F401 - re-exported via __init__ |
| 23 | from .store import HeartbeatStore | 26 | from .store import HeartbeatStore |
| 24 | from .system_ctx import SYSTEM_CTX | 27 | from .system_ctx import SYSTEM_CTX |
| 25 | 28 | ||
| @@ -97,7 +100,7 @@ class HeartbeatSweeper: | |||
| 97 | while not self._stop.is_set(): | 100 | while not self._stop.is_set(): |
| 98 | try: | 101 | try: |
| 99 | self.sweep_once() | 102 | self.sweep_once() |
| 100 | - except Exception as exc: # noqa: BLE001 — defensive | 103 | + except Exception as exc: # noqa: BLE001 - defensive |
| 101 | logger.exception("heartbeat: sweep_once raised: %s", exc) | 104 | logger.exception("heartbeat: sweep_once raised: %s", exc) |
| 102 | # Sleep interruptibly so test teardown doesn't hang. | 105 | # Sleep interruptibly so test teardown doesn't hang. |
| 103 | self._stop.wait(self._period) | 106 | self._stop.wait(self._period) |
| @@ -0,0 +1,28 @@ | |||
| 1 | +"""Image management module — register / query / deregister third-party | ||
| 2 | +framework images, with multi-version and default-version management. | ||
| 3 | + | ||
| 4 | +The registry only stores image references plus launch specs (in the image | ||
| 5 | +registry table); it does not invoke the image-processing module or make | ||
| 6 | +decisions for the gateway. The image-processing module calls | ||
| 7 | +``POST /api/images`` to register; the gateway calls | ||
| 8 | +``GET /api/images/{fw}/launch-spec`` to fetch the launch spec before | ||
| 9 | +spawning a process. | ||
| 10 | + | ||
| 11 | +Persistence goes through ``RegistryTableService`` (SQL backend); this | ||
| 12 | +module does not hold a store/backend directly. | ||
| 13 | +""" | ||
| 14 | + | ||
| 15 | +from .errors import ImageNotFoundError, ImageValidationError, RepoDeleteError | ||
| 16 | +from .service import ImageService | ||
| 17 | +from .deps import get_image_service, set_image_service | ||
| 18 | +from .router import router | ||
| 19 | + | ||
| 20 | +__all__ = [ | ||
| 21 | + "ImageService", | ||
| 22 | + "ImageNotFoundError", | ||
| 23 | + "ImageValidationError", | ||
| 24 | + "RepoDeleteError", | ||
| 25 | + "get_image_service", | ||
| 26 | + "set_image_service", | ||
| 27 | + "router", | ||
| 28 | +] | ||
| @@ -0,0 +1,28 @@ | |||
| 1 | +"""Module-level ImageService singleton + FastAPI dependency injection. | ||
| 2 | + | ||
| 3 | +Mirrors the ``a2x_registry.heartbeat.deps`` structure: a single global | ||
| 4 | +variable injected at startup and returned by ``get_image_service()``. | ||
| 5 | +``None`` means the image module is not assembled (non-appliance mode); | ||
| 6 | +the router returns 404 in that case, matching the fallback semantics of | ||
| 7 | +an uninitialized heartbeat module. | ||
| 8 | +""" | ||
| 9 | + | ||
| 10 | +from __future__ import annotations | ||
| 11 | + | ||
| 12 | +from typing import Optional | ||
| 13 | + | ||
| 14 | +from .service import ImageService | ||
| 15 | + | ||
| 16 | +_service: Optional[ImageService] = None | ||
| 17 | + | ||
| 18 | + | ||
| 19 | +def get_image_service() -> Optional[ImageService]: | ||
| 20 | + """Return the assembled ImageService, or ``None`` if not assembled.""" | ||
| 21 | + return _service | ||
| 22 | + | ||
| 23 | + | ||
| 24 | +def set_image_service(service: Optional[ImageService]) -> None: | ||
| 25 | + """Inject (or clear) the global ImageService. Called by startup | ||
| 26 | + assembly and test fixtures.""" | ||
| 27 | + global _service | ||
| 28 | + _service = service | ||
| @@ -0,0 +1,48 @@ | |||
| 1 | +"""Image management domain exceptions. | ||
| 2 | + | ||
| 3 | +Business-layer exceptions that carry no HTTP semantics. The router is | ||
| 4 | +responsible for translating them into HTTP status codes: | ||
| 5 | +- ``ImageNotFoundError`` → 404 | ||
| 6 | +- ``ImageValidationError`` → 400 | ||
| 7 | +- ``ImageInUseError`` → 409 (deregister blocked by in-use instances) | ||
| 8 | +- ``ImagePortConflictError`` → 409 (web_svc_port already used by another image name) | ||
| 9 | +- ``RepoDeleteError`` → 502 (image repository deletion failed) | ||
| 10 | + | ||
| 11 | +``ImageInUseError`` / ``ExternalDependencyError`` are reused from | ||
| 12 | +``register.errors`` to avoid duplication. | ||
| 13 | +""" | ||
| 14 | + | ||
| 15 | +from __future__ import annotations | ||
| 16 | + | ||
| 17 | +from a2x_registry.register.errors import ( | ||
| 18 | + ExternalDependencyError as RepoDeleteError, | ||
| 19 | + ImageInUseError, | ||
| 20 | + NotFoundError, | ||
| 21 | + ValidationError, | ||
| 22 | +) | ||
| 23 | + | ||
| 24 | + | ||
| 25 | +class ImageNotFoundError(NotFoundError): | ||
| 26 | + """Image (framework + version) not found. Router maps to 404.""" | ||
| 27 | + | ||
| 28 | + | ||
| 29 | +class ImageValidationError(ValidationError): | ||
| 30 | + """Image input validation failed (missing field / version conflict). | ||
| 31 | + Router maps to 400.""" | ||
| 32 | + | ||
| 33 | + | ||
| 34 | +class ImagePortConflictError(Exception): | ||
| 35 | + """A ``web_svc_port`` access-mode port already used by another image | ||
| 36 | + ``name``. | ||
| 37 | + | ||
| 38 | + Same ``name`` (different versions) may reuse a port. Router maps to 409. | ||
| 39 | + """ | ||
| 40 | + | ||
| 41 | + | ||
| 42 | +__all__ = [ | ||
| 43 | + "ImageNotFoundError", | ||
| 44 | + "ImageValidationError", | ||
| 45 | + "ImagePortConflictError", | ||
| 46 | + "ImageInUseError", | ||
| 47 | + "RepoDeleteError", | ||
| 48 | +] | ||
| @@ -0,0 +1,275 @@ | |||
| 1 | +"""Image management pydantic request / response models. | ||
| 2 | + | ||
| 3 | +The image registry is keyed by ``name`` (one row = one ``name``@``version``); | ||
| 4 | +``framework`` is demoted to a plain display field. ``version`` replaces the | ||
| 5 | +old ``framework_version`` (kept as a deprecated transition alias on | ||
| 6 | +requests / entries). New text fields ``description`` / ``package_path`` / | ||
| 7 | +``image_archive_path`` and the ``access_mode`` array (each item declares one | ||
| 8 | +access route: tui / web / …) are stored inside the ``data`` JSON. | ||
| 9 | + | ||
| 10 | +``runtime_spec`` remains an opaque JSON object passthrough (no ``ImageSpec`` | ||
| 11 | +typed structure). ``env_vars`` / ``workspace`` / ``mounts`` are top-level | ||
| 12 | +fields alongside ``runtime_spec``, aligning with the yuanrong | ||
| 13 | +``CreateAgentRequest`` layout. | ||
| 14 | +""" | ||
| 15 | + | ||
| 16 | +from __future__ import annotations | ||
| 17 | + | ||
| 18 | +import re | ||
| 19 | +from typing import Any, Dict, List, Optional | ||
| 20 | + | ||
| 21 | +from pydantic import BaseModel, Field, field_validator, model_validator | ||
| 22 | + | ||
| 23 | +# ``name`` / ``version`` are opaque passthrough identifiers, but the API also | ||
| 24 | +# uses them as URL path segments (DELETE /api/images/{name}/{version}, …). | ||
| 25 | +# Keep the check deliberately loose: bound the length and reject only values | ||
| 26 | +# that can never be addressed in a path even after percent-encoding, so every | ||
| 27 | +# accepted row stays deletable later. | ||
| 28 | +# - "/" is a path separator (Starlette decodes %2F back to "/"); | ||
| 29 | +# - C0 control chars / DEL are not URI-safe; | ||
| 30 | +# - "." / ".." are normalized away by HTTP clients; | ||
| 31 | +# - "|" in ``name`` is the separator used by ``image_sid(name, version)``: | ||
| 32 | +# allowing it would make ("a|b", "c") and ("a", "b|c") collide on the | ||
| 33 | +# same row id and silently overwrite each other. ``version`` may keep | ||
| 34 | +# "|" because a name without the separator makes the split unique. | ||
| 35 | +# | ||
| 36 | +# The per-field cap is a generous sanity bound; the real addressability guard | ||
| 37 | +# is the combined worst-case encoded budget below (percent-encoding expands | ||
| 38 | +# every UTF-8 byte to 3 URL chars). Keeping name+version under ~7 KB leaves | ||
| 39 | +# headroom below the common 8 KB request-line limit (nginx default header | ||
| 40 | +# buffer), so even long identifiers remain deletable through an ingress. | ||
| 41 | +_IDENTIFIER_MAX_LEN = 1024 | ||
| 42 | +_NAME_ID_SEPARATOR = "|" | ||
| 43 | +_PATH_UNSAFE_RE = re.compile(r"[/\x00-\x1f\x7f]") | ||
| 44 | +_PATH_PREFIX_LEN = len("/api/images//") # name + version path separators | ||
| 45 | +_PATH_ENCODED_BUDGET = 7000 # worst-case encoded bytes for the full path | ||
| 46 | + | ||
| 47 | + | ||
| 48 | +def _validate_path_safe(value: Optional[str], field_name: str) -> Optional[str]: | ||
| 49 | + """Reject only characters that break URL-path addressing (passthrough).""" | ||
| 50 | + if value is None: | ||
| 51 | + return None | ||
| 52 | + if _PATH_UNSAFE_RE.search(value): | ||
| 53 | + raise ValueError( | ||
| 54 | + f"{field_name} must not contain '/' or control characters" | ||
| 55 | + ) | ||
| 56 | + if value in (".", ".."): | ||
| 57 | + raise ValueError(f"{field_name} must not be '.' or '..'") | ||
| 58 | + return value | ||
| 59 | + | ||
| 60 | + | ||
| 61 | +class AccessMode(BaseModel): | ||
| 62 | + """One access route of an image (e.g. tui / web).""" | ||
| 63 | + | ||
| 64 | + name: str = Field(..., description="接入方式名,如 tui / web") | ||
| 65 | + port: str = Field(..., description="端口(字符串),如 18789") | ||
| 66 | + cmd: Optional[str] = Field(None, description="启动命令") | ||
| 67 | + | ||
| 68 | + | ||
| 69 | +class RegisterImageRequest(BaseModel): | ||
| 70 | + """``POST /api/images`` request body. | ||
| 71 | + | ||
| 72 | + ``name`` is the primary key (positioning); ``framework`` is a plain | ||
| 73 | + display field. ``version`` is required by the contract; the deprecated | ||
| 74 | + ``framework_version`` is accepted as a transition fallback when | ||
| 75 | + ``version`` is absent. | ||
| 76 | + | ||
| 77 | + ``name`` / ``version`` remain opaque passthrough values, but they are | ||
| 78 | + also used as URL path segments, so a loose length + path-safety check is | ||
| 79 | + applied (they must stay addressable by DELETE / launch-spec). | ||
| 80 | + """ | ||
| 81 | + | ||
| 82 | + name: str = Field( | ||
| 83 | + ..., | ||
| 84 | + max_length=_IDENTIFIER_MAX_LEN, | ||
| 85 | + description=( | ||
| 86 | + "镜像主键(取代原 framework 定位);≤1024 字符," | ||
| 87 | + "不含 '/'、控制字符或 '|',其余字符原样透传" | ||
| 88 | + ), | ||
| 89 | + ) | ||
| 90 | + framework: Optional[str] = Field( | ||
| 91 | + None, description="普通展示字段(非主键)" | ||
| 92 | + ) | ||
| 93 | + description: Optional[str] = Field(None, description="纯文本描述") | ||
| 94 | + package_path: Optional[str] = Field(None, description="包路径") | ||
| 95 | + image_archive_path: Optional[str] = Field(None, description="镜像归档路径") | ||
| 96 | + version: Optional[str] = Field( | ||
| 97 | + None, | ||
| 98 | + max_length=_IDENTIFIER_MAX_LEN, | ||
| 99 | + description=( | ||
| 100 | + "镜像版本(原 framework_version 更名);≤1024 字符," | ||
| 101 | + "不含 '/' 或控制字符" | ||
| 102 | + ), | ||
| 103 | + ) | ||
| 104 | + framework_version: Optional[str] = Field( | ||
| 105 | + None, | ||
| 106 | + max_length=_IDENTIFIER_MAX_LEN, | ||
| 107 | + description=( | ||
| 108 | + "【待删除】由 version 取代,过渡期兼容(version 缺省时的回退);" | ||
| 109 | + "约束同 version" | ||
| 110 | + ), | ||
| 111 | + ) | ||
| 112 | + runtime_spec: Dict[str, Any] = Field( | ||
| 113 | + ..., description="Opaque yuanrong RuntimeSpec JSON (passthrough)" | ||
| 114 | + ) | ||
| 115 | + access_mode: List[AccessMode] = Field( | ||
| 116 | + default_factory=list, description="接入方式数组(如 tui / web)" | ||
| 117 | + ) | ||
| 118 | + env_vars: Dict[str, str] = Field( | ||
| 119 | + default_factory=dict, description="Environment variables" | ||
| 120 | + ) | ||
| 121 | + workspace: Optional[str] = Field(None, description="Working directory") | ||
| 122 | + mounts: List[Dict[str, Any]] = Field( | ||
| 123 | + default_factory=list, description="Volume mounts" | ||
| 124 | + ) | ||
| 125 | + image_module_version: Optional[str] = Field( | ||
| 126 | + None, description="Image-processing module version" | ||
| 127 | + ) | ||
| 128 | + uploaded_by: str = Field(..., description="Uploader identity") | ||
| 129 | + | ||
| 130 | + @field_validator("name", "version", "framework_version") | ||
| 131 | + @classmethod | ||
| 132 | + def _check_identifier(cls, value: Optional[str], info) -> Optional[str]: | ||
| 133 | + value = _validate_path_safe(value, info.field_name) | ||
| 134 | + if ( | ||
| 135 | + value is not None | ||
| 136 | + and info.field_name == "name" | ||
| 137 | + and _NAME_ID_SEPARATOR in value | ||
| 138 | + ): | ||
| 139 | + raise ValueError( | ||
| 140 | + "name must not contain '|' " | ||
| 141 | + "(reserved as the image id separator)" | ||
| 142 | + ) | ||
| 143 | + return value | ||
| 144 | + | ||
| 145 | + @model_validator(mode="after") | ||
| 146 | + def _check_path_budget(self): | ||
| 147 | + """Ensure name+version still fit in a request line when encoded. | ||
| 148 | + | ||
| 149 | + Percent-encoding turns each UTF-8 byte into 3 URL chars, so the | ||
| 150 | + worst-case encoded length is ``3 * len(value.encode())``. Both | ||
| 151 | + segments share one path, hence the combined budget. | ||
| 152 | + """ | ||
| 153 | + version = self.version or self.framework_version or "" | ||
| 154 | + try: | ||
| 155 | + encoded = 3 * ( | ||
| 156 | + len(self.name.encode("utf-8")) | ||
| 157 | + + len(version.encode("utf-8")) | ||
| 158 | + ) | ||
| 159 | + except UnicodeEncodeError: | ||
| 160 | + raise ValueError( | ||
| 161 | + "name/version must be valid UTF-8" | ||
| 162 | + ) from None | ||
| 163 | + if encoded + _PATH_PREFIX_LEN > _PATH_ENCODED_BUDGET: | ||
| 164 | + raise ValueError( | ||
| 165 | + "name + version are too long for the URL path " | ||
| 166 | + f"(worst-case encoded {encoded + _PATH_PREFIX_LEN} bytes > " | ||
| 167 | + f"{_PATH_ENCODED_BUDGET}); shorten them" | ||
| 168 | + ) | ||
| 169 | + return self | ||
| 170 | + | ||
| 171 | + | ||
| 172 | +class SetDefaultRequest(BaseModel): | ||
| 173 | + """``PUT /api/images/{name}/default`` request body. | ||
| 174 | + | ||
| 175 | + ``version`` is required; the deprecated ``framework_version`` is | ||
| 176 | + accepted as a transition fallback. | ||
| 177 | + """ | ||
| 178 | + | ||
| 179 | + version: Optional[str] = Field(None, description="Version to set as default") | ||
| 180 | + framework_version: Optional[str] = Field( | ||
| 181 | + None, description="【待删除】由 version 取代,过渡期兼容回退" | ||
| 182 | + ) | ||
| 183 | + | ||
| 184 | + | ||
| 185 | +class UpdateImageRequest(BaseModel): | ||
| 186 | + """``PATCH /api/images/{name}/{version}`` request body (§8 部分更新). | ||
| 187 | + | ||
| 188 | + At least one field required. Primary key ``name`` / ``version`` and | ||
| 189 | + ``is_default`` are **not** patchable here (默认版本走 | ||
| 190 | + ``PUT …/default``); the model simply omits them. ``runtime_spec`` | ||
| 191 | + is an opaque JSON object replaced as a whole. | ||
| 192 | + """ | ||
| 193 | + | ||
| 194 | + framework: Optional[str] = Field(None, description="展示字段(非主键)") | ||
| 195 | + description: Optional[str] = Field(None, description="纯文本描述") | ||
| 196 | + package_path: Optional[str] = Field(None, description="包路径") | ||
| 197 | + image_archive_path: Optional[str] = Field(None, description="镜像归档路径") | ||
| 198 | + runtime_spec: Optional[Dict[str, Any]] = Field( | ||
| 199 | + None, description="运行规格(不透明 JSON,整体替换)" | ||
| 200 | + ) | ||
| 201 | + access_mode: Optional[List[AccessMode]] = Field( | ||
| 202 | + None, description="接入方式数组(如 tui / web)" | ||
| 203 | + ) | ||
| 204 | + env_vars: Optional[Dict[str, str]] = Field(None, description="环境变量") | ||
| 205 | + workspace: Optional[str] = Field(None, description="Working directory") | ||
| 206 | + mounts: Optional[List[Dict[str, Any]]] = Field(None, description="Volume mounts") | ||
| 207 | + | ||
| 208 | + | ||
| 209 | +class ImageRegisterResponse(BaseModel): | ||
| 210 | + """``POST /api/images`` receipt (ImageOpResponse 风格,按 name 定位)。""" | ||
| 211 | + | ||
| 212 | + name: str | ||
| 213 | + framework: Optional[str] = None | ||
| 214 | + version: str | ||
| 215 | + status: str # "registered" | "updated" | ||
| 216 | + | ||
| 217 | + | ||
| 218 | +class ImageEntry(BaseModel): | ||
| 219 | + """One flat row from the image registry (one name's one version). | ||
| 220 | + | ||
| 221 | + ``runtime_spec`` is an opaque JSON passthrough; ``description`` / | ||
| 222 | + ``package_path`` / ``image_archive_path`` / ``access_mode`` are the §6 | ||
| 223 | + additions; ``framework_version`` mirrors ``version`` during the | ||
| 224 | + transition (deprecated). | ||
| 225 | + """ | ||
| 226 | + | ||
| 227 | + name: str | ||
| 228 | + framework: Optional[str] = None | ||
| 229 | + description: Optional[str] = None | ||
| 230 | + package_path: Optional[str] = None | ||
| 231 | + image_archive_path: Optional[str] = None | ||
| 232 | + version: str | ||
| 233 | + framework_version: Optional[str] = None # deprecated, == version | ||
| 234 | + is_default: bool | ||
| 235 | + runtime_spec: Optional[Dict[str, Any]] = None | ||
| 236 | + access_mode: List[Dict[str, Any]] = Field(default_factory=list) | ||
| 237 | + workspace: Optional[str] = None | ||
| 238 | + mounts: List[Dict[str, Any]] = Field(default_factory=list) | ||
| 239 | + env_vars: Dict[str, str] = Field(default_factory=dict) | ||
| 240 | + image_module_version: Optional[str] = None | ||
| 241 | + uploaded_by: Optional[str] = None | ||
| 242 | + created_at: Optional[str] = None | ||
| 243 | + | ||
| 244 | + | ||
| 245 | +class LaunchSpecResponse(BaseModel): | ||
| 246 | + """``GET /api/images/{name}/launch-spec`` output. | ||
| 247 | + | ||
| 248 | + ``runtime_spec`` is opaque JSON passthrough; ``env_vars`` / ``workspace`` | ||
| 249 | + / ``mounts`` are top-level fields; ``access_mode`` lets the gateway | ||
| 250 | + pick a port / command to launch with. | ||
| 251 | + """ | ||
| 252 | + | ||
| 253 | + name: str | ||
| 254 | + framework: Optional[str] = None | ||
| 255 | + version: str | ||
| 256 | + runtime_spec: Optional[Dict[str, Any]] = None | ||
| 257 | + access_mode: List[Dict[str, Any]] = Field(default_factory=list) | ||
| 258 | + env_vars: Dict[str, str] = Field(default_factory=dict) | ||
| 259 | + workspace: Optional[str] = None | ||
| 260 | + mounts: List[Dict[str, Any]] = Field(default_factory=list) | ||
| 261 | + image_module_version: Optional[str] = None | ||
| 262 | + | ||
| 263 | + | ||
| 264 | +class DeregisterResponse(BaseModel): | ||
| 265 | + name: str | ||
| 266 | + framework: Optional[str] = None | ||
| 267 | + version: str | ||
| 268 | + status: str # "deregistered" | ||
| 269 | + | ||
| 270 | + | ||
| 271 | +class SetDefaultResponse(BaseModel): | ||
| 272 | + name: str | ||
| 273 | + framework: Optional[str] = None | ||
| 274 | + default: str | ||
| 275 | + status: str # "updated" | ||
| @@ -0,0 +1,205 @@ | |||
| 1 | +"""FastAPI router for image management endpoints (name 主键). | ||
| 2 | + | ||
| 3 | +Routes (mounted at app level, prefix ``/api/images``): | ||
| 4 | + | ||
| 5 | + POST /api/images register_image (image-processing module) | ||
| 6 | + GET /api/images query (user; flat, ?name / ?framework / ?uploaded_by / ?size / ?page) | ||
| 7 | + GET /api/images/{name}/launch-spec resolve_launch_spec (gateway) | ||
| 8 | + PUT /api/images/{name}/default set_default (user) | ||
| 9 | + PATCH /api/images/{name}/{version} update_image (user; partial, name/version/is_default 不可改) | ||
| 10 | + DELETE /api/images/{name}/{version} deregister (user; 409 if in use) | ||
| 11 | + | ||
| 12 | +``name`` is the image primary key (the old ``{framework}`` paths are gone); | ||
| 13 | +``framework`` remains a plain display filter. query returns flat rows (not | ||
| 14 | +grouped by name). Pagination headers (``X-Total-Count`` etc.) are set when | ||
| 15 | +``size > 0``. | ||
| 16 | + | ||
| 17 | +etcd backend infrastructure failures (``EtcdError``: unreachable / timeout / | ||
| 18 | +CAS conflict) map to HTTP 502 on every route. | ||
| 19 | +""" | ||
| 20 | + | ||
| 21 | +from __future__ import annotations | ||
| 22 | + | ||
| 23 | +import math | ||
| 24 | +import logging | ||
| 25 | +from typing import Optional | ||
| 26 | + | ||
| 27 | +from fastapi import APIRouter, HTTPException, Query, Response | ||
| 28 | + | ||
| 29 | +from a2x_registry.register.errors import ( | ||
| 30 | + NotFoundError, | ||
| 31 | + ValidationError, | ||
| 32 | +) | ||
| 33 | +from a2x_registry.register.errors import ImageInUseError, ExternalDependencyError | ||
| 34 | +from a2x_registry.register.etcd_client import EtcdError | ||
| 35 | + | ||
| 36 | +from .deps import get_image_service | ||
| 37 | +from .errors import ImagePortConflictError | ||
| 38 | +from .models import ( | ||
| 39 | + DeregisterResponse, | ||
| 40 | + ImageEntry, | ||
| 41 | + ImageRegisterResponse, | ||
| 42 | + LaunchSpecResponse, | ||
| 43 | + RegisterImageRequest, | ||
| 44 | + SetDefaultRequest, | ||
| 45 | + SetDefaultResponse, | ||
| 46 | + UpdateImageRequest, | ||
| 47 | +) | ||
| 48 | + | ||
| 49 | +logger = logging.getLogger(__name__) | ||
| 50 | + | ||
| 51 | +router = APIRouter(prefix="/api/images", tags=["image"]) | ||
| 52 | + | ||
| 53 | + | ||
| 54 | +def _resolve_service(): | ||
| 55 | + svc = get_image_service() | ||
| 56 | + if svc is None: | ||
| 57 | + raise HTTPException( | ||
| 58 | + status_code=404, | ||
| 59 | + detail=( | ||
| 60 | + "Image module not assembled (non-appliance mode). " | ||
| 61 | + "Set A2X_REGISTRY_MODE=appliance to enable." | ||
| 62 | + ), | ||
| 63 | + ) | ||
| 64 | + return svc | ||
| 65 | + | ||
| 66 | + | ||
| 67 | +@router.post("", response_model=ImageRegisterResponse) | ||
| 68 | +async def register_image(req: RegisterImageRequest): | ||
| 69 | + svc = _resolve_service() | ||
| 70 | + # 过渡期兼容:version 缺省时回退 deprecated framework_version。 | ||
| 71 | + version = req.version or req.framework_version | ||
| 72 | + try: | ||
| 73 | + result = svc.register_image( | ||
| 74 | + name=req.name, | ||
| 75 | + version=version, | ||
| 76 | + runtime_spec=req.runtime_spec, | ||
| 77 | + uploaded_by=req.uploaded_by, | ||
| 78 | + framework=req.framework, | ||
| 79 | + description=req.description, | ||
| 80 | + package_path=req.package_path, | ||
| 81 | + image_archive_path=req.image_archive_path, | ||
| 82 | + access_mode=[am.model_dump() for am in req.access_mode], | ||
| 83 | + env_vars=req.env_vars, | ||
| 84 | + workspace=req.workspace, | ||
| 85 | + mounts=req.mounts, | ||
| 86 | + image_module_version=req.image_module_version, | ||
| 87 | + ) | ||
| 88 | + except ValidationError as exc: | ||
| 89 | + raise HTTPException(status_code=400, detail=str(exc)) | ||
| 90 | + except ImagePortConflictError as exc: | ||
| 91 | + raise HTTPException(status_code=409, detail=str(exc)) | ||
| 92 | + except EtcdError as exc: | ||
| 93 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 94 | + return result | ||
| 95 | + | ||
| 96 | + | ||
| 97 | +@router.get("", response_model=list[ImageEntry]) | ||
| 98 | +async def list_images( | ||
| 99 | + name: Optional[str] = Query(None, description="按镜像主键 name 筛选"), | ||
| 100 | + framework: Optional[str] = Query(None, description="按 framework 展示字段筛选"), | ||
| 101 | + uploaded_by: Optional[str] = Query(None), | ||
| 102 | + size: int = Query(-1, ge=-1, description="Page size; -1 = no pagination"), | ||
| 103 | + page: int = Query(1, ge=1, description="Page number (1-based)"), | ||
| 104 | + response: Response = None, # noqa: B008 - FastAPI injected | ||
| 105 | +): | ||
| 106 | + """Query images (flat, one row per name version).""" | ||
| 107 | + svc = _resolve_service() | ||
| 108 | + try: | ||
| 109 | + rows, total = svc.query( | ||
| 110 | + name=name, | ||
| 111 | + framework=framework, | ||
| 112 | + uploaded_by=uploaded_by, | ||
| 113 | + size=size, | ||
| 114 | + page=page, | ||
| 115 | + ) | ||
| 116 | + except EtcdError as exc: | ||
| 117 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 118 | + if size > 0: | ||
| 119 | + response.headers["X-Total-Count"] = str(total) | ||
| 120 | + response.headers["X-Page"] = str(page) | ||
| 121 | + response.headers["X-Total-Pages"] = str( | ||
| 122 | + max(1, math.ceil(total / size)) if total > 0 else 1 | ||
| 123 | + ) | ||
| 124 | + response.headers["X-Page-Size"] = str(len(rows)) | ||
| 125 | + return rows | ||
| 126 | + | ||
| 127 | + | ||
| 128 | +@router.get("/{name}/launch-spec", response_model=LaunchSpecResponse) | ||
| 129 | +async def get_launch_spec( | ||
| 130 | + name: str, | ||
| 131 | + version: Optional[str] = Query(None), | ||
| 132 | +): | ||
| 133 | + svc = _resolve_service() | ||
| 134 | + try: | ||
| 135 | + return svc.resolve_launch_spec(name, version=version) | ||
| 136 | + except NotFoundError as exc: | ||
| 137 | + raise HTTPException(status_code=404, detail=str(exc)) | ||
| 138 | + except EtcdError as exc: | ||
| 139 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 140 | + | ||
| 141 | + | ||
| 142 | +@router.put("/{name}/default", response_model=SetDefaultResponse) | ||
| 143 | +async def set_default(name: str, req: SetDefaultRequest): | ||
| 144 | + svc = _resolve_service() | ||
| 145 | + version = req.version or req.framework_version | ||
| 146 | + if not version: | ||
| 147 | + raise HTTPException( | ||
| 148 | + status_code=400, detail="version must not be empty" | ||
| 149 | + ) | ||
| 150 | + try: | ||
| 151 | + return svc.set_default(name, version) | ||
| 152 | + except NotFoundError as exc: | ||
| 153 | + raise HTTPException(status_code=404, detail=str(exc)) | ||
| 154 | + except EtcdError as exc: | ||
| 155 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 156 | + | ||
| 157 | + | ||
| 158 | +@router.patch("/{name}/{version}", response_model=ImageEntry) | ||
| 159 | +async def update_image(name: str, version: str, req: UpdateImageRequest): | ||
| 160 | + """Partially update mutable fields of one image version (§8). | ||
| 161 | + | ||
| 162 | + At least one field required; primary key ``name`` / ``version`` and | ||
| 163 | + ``is_default`` are not patchable (默认版本走 ``PUT …/default``). | ||
| 164 | + Returns the updated entry. | ||
| 165 | + """ | ||
| 166 | + svc = _resolve_service() | ||
| 167 | + # model_dump() 递归展开 access_mode 的 AccessMode 子模型; | ||
| 168 | + # None 字段剔除("未给 = 不改")。 | ||
| 169 | + fields = {k: v for k, v in req.model_dump().items() if v is not None} | ||
| 170 | + try: | ||
| 171 | + return svc.update_image(name, version, fields) | ||
| 172 | + except NotFoundError as exc: | ||
| 173 | + raise HTTPException(status_code=404, detail=str(exc)) | ||
| 174 | + except ValidationError as exc: | ||
| 175 | + raise HTTPException(status_code=400, detail=str(exc)) | ||
| 176 | + except ImagePortConflictError as exc: | ||
| 177 | + raise HTTPException(status_code=409, detail=str(exc)) | ||
| 178 | + except ImageInUseError as exc: | ||
| 179 | + raise HTTPException(status_code=409, detail=str(exc)) | ||
| 180 | + except EtcdError as exc: | ||
| 181 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 182 | + | ||
| 183 | + | ||
| 184 | +@router.delete("/{name}/{version}", response_model=DeregisterResponse) | ||
| 185 | +async def deregister_image(name: str, version: str): | ||
| 186 | + svc = _resolve_service() | ||
| 187 | + try: | ||
| 188 | + return svc.deregister(name, version) | ||
| 189 | + except NotFoundError as exc: | ||
| 190 | + raise HTTPException(status_code=404, detail=str(exc)) | ||
| 191 | + except ImageInUseError as exc: | ||
| 192 | + # 按 OpenAPI ImageInUseError schema 组装结构化错误体: | ||
| 193 | + # {code: image_in_use, detail, instances: [service_id, ...]} | ||
| 194 | + raise HTTPException( | ||
| 195 | + status_code=409, | ||
| 196 | + detail={ | ||
| 197 | + "code": "image_in_use", | ||
| 198 | + "detail": str(exc), | ||
| 199 | + "instances": exc.instances, | ||
| 200 | + }, | ||
| 201 | + ) | ||
| 202 | + except ExternalDependencyError as exc: | ||
| 203 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| 204 | + except EtcdError as exc: | ||
| 205 | + raise HTTPException(status_code=502, detail=str(exc)) | ||
| @@ -0,0 +1,610 @@ | |||
| 1 | +"""ImageService -- image management business logic (name 主键). | ||
| 2 | + | ||
| 3 | +Responsibilities: | ||
| 4 | +- ``register_image``: insert one row (name+version, idempotent upsert); | ||
| 5 | + write ``version_key`` and ``uploaded_by`` as promoted columns; store flat | ||
| 6 | + ``data`` JSON (no ``rootfs`` wrapper); auto-set ``is_default`` when the | ||
| 7 | + name has no default yet. New §6 fields (``description`` / | ||
| 8 | + ``package_path`` / ``image_archive_path`` / ``access_mode``) live inside | ||
| 9 | + ``data``. | ||
| 10 | +- ``query``: return **flat** rows (one row per name version) with optional | ||
| 11 | + ``name`` / ``framework`` / ``uploaded_by`` filters and SQL-side pagination | ||
| 12 | + (``LIMIT/OFFSET``). Returns ``(rows, total)`` tuple. | ||
| 13 | +- ``update_image``: partially update mutable fields of one row (§8) - | ||
| 14 | + ``framework`` as a promoted column, the rest merged into ``data`` | ||
| 15 | + read-modify-write; primary key / ``is_default`` untouched. | ||
| 16 | +- ``deregister``: verify no in-use instances; delete repo image file (stub) | ||
| 17 | + and delete the row; promote the latest remaining version to default. | ||
| 18 | +- ``set_default`` / ``get_default_version``: default-version management | ||
| 19 | + (one default per name). | ||
| 20 | +- ``resolve_launch_spec``: assemble flat launch spec for the gateway. | ||
| 21 | + | ||
| 22 | +In-use check: instance rows still carry ``framework`` / ``framework_version`` | ||
| 23 | +(instance contract unchanged this batch), so an image is "in use" when an | ||
| 24 | +instance references its display ``framework`` + ``version``. Renaming the | ||
| 25 | +``framework`` of an in-use image is rejected, | ||
| 26 | +so a rename can never orphan instance references. | ||
| 27 | + | ||
| 28 | +Persistence goes through ``RegistryTableService``; this service does not | ||
| 29 | +hold a backend/store directly. | ||
| 30 | +""" | ||
| 31 | + | ||
| 32 | +from __future__ import annotations | ||
| 33 | + | ||
| 34 | +import logging | ||
| 35 | +import os | ||
| 36 | +from typing import Any, Dict, List, Optional, Tuple | ||
| 37 | + | ||
| 38 | +from a2x_registry.common.ids import image_sid, now_iso | ||
| 39 | +from a2x_registry.register.table_repo import TableRepo | ||
| 40 | + | ||
| 41 | +from .errors import ( | ||
| 42 | + ImageInUseError, | ||
| 43 | + ImageNotFoundError, | ||
| 44 | + ImagePortConflictError, | ||
| 45 | + ImageValidationError, | ||
| 46 | +) | ||
| 47 | +from .version_key import version_key | ||
| 48 | + | ||
| 49 | +logger = logging.getLogger(__name__) | ||
| 50 | + | ||
| 51 | +IMAGE_REGISTRY = "images" | ||
| 52 | +INSTANCE_REGISTRY = "instances" | ||
| 53 | + | ||
| 54 | +# Web access-mode port allocation window: a ``web_svc_port`` entry's ``port`` | ||
| 55 | +# must be an integer within [WEB_PORT_MIN, WEB_PORT_MAX]. Plain constants for | ||
| 56 | +# now — will become configurable later. (The legacy ``web`` name is NOT | ||
| 57 | +# validated — it was used for a different purpose by old clients.) | ||
| 58 | +WEB_PORT_MIN = 19101 | ||
| 59 | +WEB_PORT_MAX = 19200 | ||
| 60 | +_WEB_ACCESS_NAME = "web_svc_port" | ||
| 61 | + | ||
| 62 | +# Image repo deletion env var. | ||
| 63 | +_ENV_REPO_BASE = "A2X_REGISTRY_REPO_BASE" | ||
| 64 | + | ||
| 65 | +# Structured sort spec for image queries (flat, name ASC, version_key DESC). | ||
| 66 | +_IMAGE_ORDER = ( | ||
| 67 | + "name asc", | ||
| 68 | + "version_key desc", | ||
| 69 | + "data.created_at desc", | ||
| 70 | +) | ||
| 71 | + | ||
| 72 | +# Mutable ``data``-JSON fields patchable via ``update_image`` (§8). | ||
| 73 | +# Everything else inside ``data`` (image_module_version / created_at) is | ||
| 74 | +# not patchable via the image PATCH endpoint. | ||
| 75 | +_MUTABLE_DATA_FIELDS = ( | ||
| 76 | + "description", | ||
| 77 | + "package_path", | ||
| 78 | + "image_archive_path", | ||
| 79 | + "runtime_spec", | ||
| 80 | + "access_mode", | ||
| 81 | + "env_vars", | ||
| 82 | + "workspace", | ||
| 83 | + "mounts", | ||
| 84 | +) | ||
| 85 | + | ||
| 86 | + | ||
| 87 | +class ImageService: | ||
| 88 | + """Image management business layer.""" | ||
| 89 | + | ||
| 90 | + __slots__ = ("_table_svc",) | ||
| 91 | + | ||
| 92 | + def __init__(self, table_svc: TableRepo) -> None: | ||
| 93 | + self._table_svc = table_svc | ||
| 94 | + | ||
| 95 | + # ------------------------------------------------------------------ | ||
| 96 | + # register_image | ||
| 97 | + # ------------------------------------------------------------------ | ||
| 98 | + | ||
| 99 | + def register_image( | ||
| 100 | + self, | ||
| @@ -0,0 +1,44 @@ | |||
| 1 | +"""Semantic version normalization key for image ordering. | ||
| 2 | + | ||
| 3 | +``version_key(framework_version)`` produces a fixed-width sortable string | ||
| 4 | +so that ``ORDER BY version_key DESC`` correctly orders versions: | ||
| 5 | + | ||
| 6 | + v0.2.0 -> 00000.00002.00000~ | ||
| 7 | + v0.10.0 -> 00000.00010.00000~ | ||
| 8 | + v0.2.0-beta -> 00000.00002.00000-beta | ||
| 9 | + | ||
| 10 | +The trailing ``~`` (ASCII 0x7E) is higher than any letter or ``-``, so | ||
| 11 | +in DESC order formal releases appear before pre-releases of the same | ||
| 12 | +version. Non-semver strings get a zeroed-out key and sort last within | ||
| 13 | +their framework group (secondary sort by ``created_at``). | ||
| 14 | +""" | ||
| 15 | + | ||
| 16 | +from __future__ import annotations | ||
| 17 | + | ||
| 18 | +import re | ||
| 19 | + | ||
| 20 | +_SEMVER = re.compile(r"^v?(\d+)\.(\d+)\.(\d+)(?:-(.+))?$") | ||
| 21 | + | ||
| 22 | + | ||
| 23 | +def version_key(framework_version: str) -> str: | ||
| 24 | + """Convert a framework version string to a normalized sort key. | ||
| 25 | + | ||
| 26 | + Examples: | ||
| 27 | + >>> version_key("v0.2.0") | ||
| 28 | + '00000.00002.00000~' | ||
| 29 | + >>> version_key("v0.10.0") | ||
| 30 | + '00000.00010.00000~' | ||
| 31 | + >>> version_key("v0.2.0-beta") | ||
| 32 | + '00000.00002.00000-beta' | ||
| 33 | + >>> version_key("nightly") | ||
| 34 | + '00000.00000.00000' | ||
| 35 | + | ||
| 36 | + Non-semver strings (no match) return all zeros and are sorted last | ||
| 37 | + within their framework via secondary sort on ``created_at``. | ||
| 38 | + """ | ||
| 39 | + m = _SEMVER.match(framework_version.strip()) | ||
| 40 | + if not m: | ||
| 41 | + return "00000.00000.00000" | ||
| 42 | + major, minor, patch, pre = m.groups() | ||
| 43 | + base = f"{int(major):05d}.{int(minor):05d}.{int(patch):05d}" | ||
| 44 | + return f"{base}-{pre}" if pre else f"{base}~" | ||
| @@ -0,0 +1,28 @@ | |||
| 1 | +"""Instance management module — register / query / update / deregister | ||
| 2 | +instances (三方 / 九问 unified flow). | ||
| 3 | + | ||
| 4 | +The registry only stores instance references plus their node/address; it | ||
| 5 | +does not invoke the runtime (元戎) or make decisions for the gateway. | ||
| 6 | +The gateway calls ``POST /api/instances`` after launching an instance; | ||
| 7 | +``GET /api/instances`` returns the list with the persisted ``status``. | ||
| 8 | + | ||
| 9 | +Persistence goes through ``RegistryTableService`` (SQL backend); this | ||
| 10 | +module does not hold a store/backend directly. ``status`` (运行 / 停止 / | ||
| 11 | +异常) is persisted inside the row's ``data`` JSON and written by the | ||
| 12 | +gateway via ``PATCH /api/instances/{service_id}`` (元戎 List) — the | ||
| 13 | +registry does NOT receive heartbeats or derive status. | ||
| 14 | +""" | ||
| 15 | + | ||
| 16 | +from .errors import InstanceNotFoundError, InstanceValidationError | ||
| 17 | +from .service import InstanceService | ||
| 18 | +from .deps import get_instance_service, set_instance_service | ||
| 19 | +from .router import router | ||
| 20 | + | ||
| 21 | +__all__ = [ | ||
| 22 | + "InstanceService", | ||
| 23 | + "InstanceNotFoundError", | ||
| 24 | + "InstanceValidationError", | ||
| 25 | + "get_instance_service", | ||
| 26 | + "set_instance_service", | ||
| 27 | + "router", | ||
| 28 | +] | ||
| @@ -0,0 +1,57 @@ | |||
| 1 | +"""Instance 模块常量统一管理。 | ||
| 2 | + | ||
| 3 | +按约定集中存放本模块(a2x_registry.instance)的全部常量,并用注释区分: | ||
| 4 | + | ||
| 5 | +- **可配置常量**:可经环境变量 / 装配参数调整(括号内标注环境变量名与默认值), | ||
| 6 | + 由 ``backend/startup.py`` 读取后经构造函数注入,业务代码不直接读环境变量。 | ||
| 7 | +- **不可配置常量**:进程内固定值,调整需改代码。 | ||
| 8 | +""" | ||
| 9 | + | ||
| 10 | +from __future__ import annotations | ||
| 11 | + | ||
| 12 | +# ══ 可配置常量(环境变量注入)════════════════════════════════════════ | ||
| 13 | + | ||
| 14 | +# 元戎 frontend 地址;空 = 未配置(模式 B 请求 → 501 runtime_not_configured) | ||
| 15 | +YUANRONG_ENDPOINT_ENV = "A2X_REGISTRY_YUANRONG_ENDPOINT" | ||
| 16 | + | ||
| 17 | +# 元戎命名空间(registry 配置优先,不信任请求入参的 namespace) | ||
| 18 | +# (A2X_REGISTRY_YUANRONG_NAMESPACE,默认 "default") | ||
| 19 | +YUANRONG_NAMESPACE_ENV = "A2X_REGISTRY_YUANRONG_NAMESPACE" | ||
| 20 | +YUANRONG_NAMESPACE_DEFAULT = "default" | ||
| 21 | + | ||
| 22 | +# 元戎单次 HTTP 超时秒数(A2X_REGISTRY_YUANRONG_TIMEOUT_SECONDS,默认 300) | ||
| 23 | +YUANRONG_TIMEOUT_S_ENV = "A2X_REGISTRY_YUANRONG_TIMEOUT_SECONDS" | ||
| 24 | +YUANRONG_TIMEOUT_S_DEFAULT = 300.0 | ||
| 25 | + | ||
| 26 | +# 模式 B 创建后等待元戎 status=running 的上限秒数;0 = 不等待立即返回 | ||
| 27 | +# (A2X_REGISTRY_YUANRONG_WAIT_RUNNING_SECONDS,默认 60) | ||
| 28 | +YUANRONG_WAIT_RUNNING_S_ENV = "A2X_REGISTRY_YUANRONG_WAIT_RUNNING_SECONDS" | ||
| 29 | +YUANRONG_WAIT_RUNNING_S_DEFAULT = 60.0 | ||
| 30 | + | ||
| 31 | +# 等待 running 的轮询间隔秒数(A2X_REGISTRY_YUANRONG_WAIT_INTERVAL_SECONDS,默认 1) | ||
| 32 | +YUANRONG_WAIT_INTERVAL_S_ENV = "A2X_REGISTRY_YUANRONG_WAIT_INTERVAL_SECONDS" | ||
| 33 | +YUANRONG_WAIT_INTERVAL_S_DEFAULT = 1.0 | ||
| 34 | + | ||
| 35 | +# ══ 不可配置常量(进程内固定)════════════════════════════════════════ | ||
| 36 | + | ||
| 37 | +# 同 service_id 在途操作互斥:锁获取等待上限(超时 → 409 in_progress) | ||
| 38 | +LOCK_WAIT_S = 5.0 | ||
| 39 | + | ||
| 40 | +# 元戎成功后条目写入 / 删除的失败重试次数(仍失败 → 500 + 留日志待对账) | ||
| 41 | +ENTRY_WRITE_RETRIES = 3 | ||
| 42 | + | ||
| 43 | +# DELETE ALL 批量调元戎的并发上限(asyncio.Semaphore) | ||
| 44 | +ALL_CONCURRENCY = 8 | ||
| 45 | + | ||
| 46 | +# 九问 builtin 框架名:模式 B 里 framework == 该值 → kind = 九问 | ||
| 47 | +BUILTIN_AGENT_FRAMEWORK = "jiuwenswarm" | ||
| 48 | + | ||
| 49 | +# 实例种类与生命周期状态(OpenAPI 枚举) | ||
| 50 | +VALID_KINDS = ("三方", "九问") | ||
| 51 | +VALID_STATUSES = ("运行", "停止", "异常") | ||
| 52 | +STATUS_RUNNING = "运行" | ||
| 53 | +STATUS_STOPPED = "停止" | ||
| 54 | + | ||
| 55 | +# 元戎 GET /api/agent/:id 的实例状态语义 | ||
| 56 | +AGENT_RUNNING_STATUS = "running" | ||
| 57 | +AGENT_FAILED_STATUSES = frozenset({"failed", "error", "deleted", "stopped", "killed"}) | ||
| @@ -0,0 +1,28 @@ | |||
| 1 | +"""Module-level InstanceService singleton + FastAPI dependency injection. | ||
| 2 | + | ||
| 3 | +Mirrors the ``a2x_registry.image.deps`` structure: a single global | ||
| 4 | +variable injected at startup and returned by ``get_instance_service()``. | ||
| 5 | +``None`` means the instance module is not assembled (non-appliance mode); | ||
| 6 | +the router returns 404 in that case, matching the fallback semantics of | ||
| 7 | +an uninitialized heartbeat module. | ||
| 8 | +""" | ||
| 9 | + | ||
| 10 | +from __future__ import annotations | ||
| 11 | + | ||
| 12 | +from typing import Optional | ||
| 13 | + | ||
| 14 | +from .service import InstanceService | ||
| 15 | + | ||
| 16 | +_service: Optional[InstanceService] = None | ||
| 17 | + | ||
| 18 | + | ||
| 19 | +def get_instance_service() -> Optional[InstanceService]: | ||
| 20 | + """Return the assembled InstanceService, or ``None`` if not assembled.""" | ||
| 21 | + return _service | ||
| 22 | + | ||
| 23 | + | ||
| 24 | +def set_instance_service(service: Optional[InstanceService]) -> None: | ||
| 25 | + """Inject (or clear) the global InstanceService. Called by startup | ||
| 26 | + assembly and test fixtures.""" | ||
| 27 | + global _service | ||
| 28 | + _service = service | ||
| @@ -0,0 +1,57 @@ | |||
| 1 | +"""Instance management domain exceptions. | ||
| 2 | + | ||
| 3 | +Business-layer exceptions that carry no HTTP semantics. The router is | ||
| 4 | +responsible for translating them into HTTP status codes: | ||
| 5 | +- ``InstanceNotFoundError`` → 404 | ||
| 6 | +- ``InstanceValidationError`` → 400 | ||
| 7 | +- ``InstanceInProgressError`` → 409(同 service_id 在途创建 / 删除) | ||
| 8 | +- ``RuntimeNotConfiguredError`` → 501(模式 B 但未配置元戎连接) | ||
| 9 | +- ``YuanrongFailedError`` → 502(元戎创建 / 删除失败,含同名冲突透传) | ||
| 10 | +- ``YuanrongTimeoutError`` → 504(元戎请求 / 等待 running 超时) | ||
| 11 | +- ``InstanceStoreError`` → 500(元戎成功后条目写入 / 删除重试耗尽, | ||
| 12 | + 孤儿实例 / 僵尸条目留日志待对账) | ||
| 13 | +""" | ||
| 14 | + | ||
| 15 | +from __future__ import annotations | ||
| 16 | + | ||
| 17 | +from a2x_registry.register.errors import NotFoundError, ValidationError | ||
| 18 | + | ||
| 19 | + | ||
| 20 | +class InstanceNotFoundError(NotFoundError): | ||
| 21 | + """Instance (service_id) not found. Router maps to 404.""" | ||
| 22 | + | ||
| 23 | + | ||
| 24 | +class InstanceValidationError(ValidationError): | ||
| 25 | + """Instance input validation failed (missing field / invalid kind). | ||
| 26 | + Router maps to 400.""" | ||
| 27 | + | ||
| 28 | + | ||
| 29 | +class InstanceInProgressError(Exception): | ||
| 30 | + """同 service_id 已有在途创建 / 删除,拒绝并发。Router maps to 409.""" | ||
| 31 | + | ||
| 32 | + | ||
| 33 | +class RuntimeNotConfiguredError(Exception): | ||
| 34 | + """模式 B 请求但未配置元戎连接。Router maps to 501.""" | ||
| 35 | + | ||
| 36 | + | ||
| 37 | +class YuanrongFailedError(Exception): | ||
| 38 | + """元戎创建 / 删除失败(外部依赖,含同名冲突透传)。Router maps to 502.""" | ||
| 39 | + | ||
| 40 | + | ||
| 41 | +class YuanrongTimeoutError(Exception): | ||
| 42 | + """元戎请求或等待 running 超时。Router maps to 504.""" | ||
| 43 | + | ||
| 44 | + | ||
| 45 | +class InstanceStoreError(Exception): | ||
| 46 | + """元戎成功后条目写入 / 删除重试耗尽(数据层故障)。Router maps to 500.""" | ||
| 47 | + | ||
| 48 | + | ||
| 49 | +__all__ = [ | ||
| 50 | + "InstanceNotFoundError", | ||
| 51 | + "InstanceValidationError", | ||
| 52 | + "InstanceInProgressError", | ||
| 53 | + "RuntimeNotConfiguredError", | ||
| 54 | + "YuanrongFailedError", | ||
| 55 | + "YuanrongTimeoutError", | ||
| 56 | + "InstanceStoreError", | ||
| 57 | +] | ||
| @@ -0,0 +1,139 @@ | |||
| 1 | +"""Instance management pydantic request / response models. | ||
| 2 | + | ||
| 3 | +Maps to the OpenAPI schemas (registry_openapi.yaml §/api/instances): | ||
| 4 | +- ``RegisterInstanceRequest``: gateway registers an instance after | ||
| 5 | + launching it (三方 / 九问 unified flow). | ||
| 6 | +- ``UpdateInstanceRequest``: gateway updates node/address/instance_id on | ||
| 7 | + migration, or sets ``status`` (运行 / 停止 / 异常) from the 元戎 List. | ||
| 8 | +- ``InstanceEntry``: full entry with ``status`` (运行 / 停止 / 异常). | ||
| 9 | +- ``InstanceDeleteResponse``: deregister result with ``deleted`` flag. | ||
| 10 | + | ||
| 11 | +``status`` is persisted inside the ``data`` JSON (default 运行 on | ||
| 12 | +register, written by the gateway via PATCH); when the node heartbeat | ||
| 13 | +marks a node UNHEALTHY the derived status shown is 异常 (see | ||
| 14 | +InstanceService._derive_status). ``instance_id`` is the 元戎 instance | ||
| 15 | +ID backfilled by the gateway — optional (empty when not launched via | ||
| 16 | +元戎) and never a primary key. | ||
| 17 | +""" | ||
| 18 | + | ||
| 19 | +from __future__ import annotations | ||
| 20 | + | ||
| 21 | +from typing import Any, Dict, List, Optional | ||
| 22 | + | ||
| 23 | +from pydantic import BaseModel, Field | ||
| 24 | + | ||
| 25 | + | ||
| 26 | +class RegisterInstanceRequest(BaseModel): | ||
| 27 | + """``POST /api/instances`` request body(模式 A:仅登记,向前兼容). | ||
| 28 | + | ||
| 29 | + All fields except ``instance_id`` / ``image_name`` are provided by the | ||
| 30 | + gateway; ``service_id`` is derived from (user, framework) by the gateway | ||
| 31 | + for idempotent upsert. ``instance_id`` is the 元戎 instance ID — | ||
| 32 | + optional (empty when the instance was not launched via 元戎). | ||
| 33 | + ``image_name`` is the image primary-key reference used by the image | ||
| 34 | + in-use check (optional; legacy rows fall back to framework matching). | ||
| 35 | + """ | ||
| 36 | + | ||
| 37 | + service_id: str = Field(..., description="user+framework 派生(幂等)") | ||
| 38 | + kind: str = Field(..., description="实例种类:三方 / 九问") | ||
| 39 | + framework: str = Field(..., description="框架名") | ||
| 40 | + framework_version: str = Field(..., description="框架版本") | ||
| 41 | + image_name: Optional[str] = Field( | ||
| 42 | + None, description="镜像主键 name(可选;空则镜像在用校验退回 framework 匹配)" | ||
| 43 | + ) | ||
| 44 | + node: str = Field("", description="元戎落点 nodeIP(可空,后续 PATCH 补写)") | ||
| 45 | + instance_id: Optional[str] = Field( | ||
| 46 | + None, description="元戎实例 ID(gateway 拉起后回填;非元戎拉起可空、不做主键)" | ||
| 47 | + ) | ||
| 48 | + address: str = Field("", description="实例访问地址 (IP:port)(可空,后续 PATCH 补写)") | ||
| 49 | + user: str = Field(..., description="创建 / 所属用户") | ||
| 50 | + | ||
| 51 | + | ||
| 52 | +class CreateInstanceRuntimeRequest(BaseModel): | ||
| 53 | + """``POST /api/instances`` request body(模式 B:registry 调元戎创建). | ||
| 54 | + | ||
| 55 | + = 元戎 create payload + version。``service_id = name``(首个 ``+`` 拆 | ||
| 56 | + user/framework)、``kind`` 由 framework 判、``node``/``address``/ | ||
| 57 | + ``instance_id`` 元戎回填。**有无 runtime_spec 是与模式 A 的判据**。 | ||
| 58 | + 实例行冗余存 ``image_name``(镜像主键引用),供镜像注销在用校验按主键关联。 | ||
| 59 | + """ | ||
| 60 | + | ||
| 61 | + name: str = Field(..., description="实例主键 = user+framework(= 元戎 name)") | ||
| 62 | + workspace: str = Field(..., description="绝对路径") | ||
| 63 | + version: str = Field(..., description="镜像版本(注册中心专属,注销校验用)") | ||
| 64 | + image_name: Optional[str] = Field( | ||
| 65 | + None, description="镜像主键 name(在用校验按主键关联的引用键)" | ||
| 66 | + ) | ||
| 67 | + namespace: Optional[str] = Field( | ||
| 68 | + None, description="元戎命名空间(可选;registry 配置优先,入参被忽略)" | ||
| 69 | + ) | ||
| 70 | + runtime_spec: Dict[str, Any] = Field( | ||
| 71 | + ..., description="元戎沙箱运行规格(runtime / rootfs.imageurl / cpu / memory…),原样转发" | ||
| 72 | + ) | ||
| 73 | + env_vars: Optional[Dict[str, str]] = Field(None, description="环境变量") | ||
| 74 | + mounts: Optional[List[Dict[str, Any]]] = Field(None, description="挂载列表") | ||
| 75 | + | ||
| 76 | + | ||
| 77 | +class UpdateInstanceRequest(BaseModel): | ||
| 78 | + """``PATCH /api/instances/{service_id}`` request body. | ||
| 79 | + | ||
| 80 | + At least one of node/address/instance_id/status must be provided. | ||
| 81 | + ``service_id`` is immutable (passed via the path). | ||
| 82 | + """ | ||
| 83 | + | ||
| 84 | + node: Optional[str] = Field(None, description="新落点 nodeIP") | ||
| 85 | + address: Optional[str] = Field(None, description="新访问地址") | ||
| 86 | + instance_id: Optional[str] = Field( | ||
| 87 | + None, description="元戎实例 ID(元戎迁移后变化时回填)" | ||
| 88 | + ) | ||
| 89 | + status: Optional[str] = Field( | ||
| 90 | + None, description="存活状态(gateway 据元戎 List 写入):运行 / 停止 / 异常" | ||
| 91 | + ) | ||
| 92 | + | ||
| 93 | + | ||
| 94 | +class InstanceEntry(BaseModel): | ||
| 95 | + """实例注册条目(含落库 status 与元戎 instance_id)。""" | ||
| 96 | + | ||
| 97 | + service_id: str | ||
| 98 | + kind: str | ||
| 99 | + framework: str | ||
| 100 | + framework_version: str | ||
| 101 | + node: str | ||
| 102 | + address: str | ||
| 103 | + instance_id: str = "" | ||
| 104 | + image_name: str = "" | ||
| 105 | + user: str | ||
| 106 | + created_at: str | ||
| 107 | + last_active_at: str | ||
| 108 | + status: str # 运行 | 停止 | 异常 | ||
| 109 | + | ||
| 110 | + | ||
| 111 | +class InstanceDeleteResponse(BaseModel): | ||
| 112 | + """注销实例回执。``deleted=False`` 表示条目本就不存在(幂等)。 | ||
| 113 | + | ||
| 114 | + ``runtime_deleted`` 仅 ``with_runtime=true``(模式 B)时返回: | ||
| 115 | + 元戎实例已删(含元戎本就不存在的幂等情形)为 True;条目无 | ||
| 116 | + instance_id 仅删条目为 False;模式 A 缺省。 | ||
| 117 | + """ | ||
| 118 | + | ||
| 119 | + service_id: str | ||
| 120 | + deleted: bool | ||
| 121 | + runtime_deleted: Optional[bool] = None | ||
| 122 | + | ||
| 123 | + | ||
| 124 | +class BatchDeleteResultItem(BaseModel): | ||
| 125 | + """ALL / 批量删除的单条结果(部分失败不回滚)。""" | ||
| 126 | + | ||
| 127 | + service_id: str | ||
| 128 | + deleted: bool | ||
| 129 | + error: Optional[str] = Field( | ||
| 130 | + None, description='该条失败原因(如 "in_progress" / 元戎失败信息);成功时缺省' | ||
| 131 | + ) | ||
| 132 | + | ||
| 133 | + | ||
| 134 | +class BatchDeleteResponse(BaseModel): | ||
| 135 | + """DELETE /api/instances/ALL 的批量回执。""" | ||
| 136 | + | ||
| 137 | + total: int | ||
| 138 | + deleted: int | ||
| 139 | + results: List[BatchDeleteResultItem] | ||