Merged
chore(registry): 同步特性分支的注册中心代码到develop分支 #375
chore(registry): 同步特性分支的注册中心代码到develop分支 #375
Merged
dingyichen1Add on 18 days ago
Total: 82 files changed+13349-240
@@ -386,49 +386,49 @@ def format_report_markdown(analysis: Dict[str, Any]) -> str:
386 386 
387 # Error Type Explanation387 # 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 - Detailed393 # 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 tools490 # 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 tools505 # 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 @@
3Per-namespace opt-in: a registry remains fully anonymous until3Per-namespace opt-in: a registry remains fully anonymous until
4``a2x-registry auth init`` runs, and individual namespaces stay anonymous4``a2x-registry auth init`` runs, and individual namespaces stay anonymous
5unless they were created with ``auth_required=true``. See5unless 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 
8Public API:10Public API:
9 - ``AuthStore`` — file-backed credential store11 - ``AuthStore`` — file-backed credential store
@@ -2,9 +2,26 @@
2 2 
3Usage:3Usage:
4 a2x-registry # API on http://127.0.0.1:80004 a2x-registry # API on http://127.0.0.1:8000
5- a2x-registry --port 8080 # Custom port5+ a2x-registry --port 8080 # Port override (env wins if set)
6 python -m a2x_registry.backend # equivalent module-form invocation6 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+ 
8Auth admin subcommands (no server needed):25Auth admin subcommands (no server needed):
9 a2x-registry auth init # bootstrap first admin key26 a2x-registry auth init # bootstrap first admin key
10 a2x-registry auth reset-admin --confirm # rotate the bootstrap admin27 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 state31 a2x-registry cluster status # show sync state
15"""32"""
16 33 
34+from __future__ import annotations
35+ 
17import argparse36import argparse
37+import logging
38+import os
18import sys39import 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 dispatcher49+_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 uvicorn228+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 auth256+ """Start the uvicorn server using env-driven config.
49- CLI; otherwise run the original ``serve`` path. This keeps every257+ 
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`` subcommand259+ 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_main308 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
17from a2x_registry.auth.router import router as auth_router17from a2x_registry.auth.router import router as auth_router
18from a2x_registry.heartbeat.router import router as heartbeat_router18from a2x_registry.heartbeat.router import router as heartbeat_router
19from a2x_registry.cluster.router import router as cluster_router19from 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 
21app = FastAPI(23app = 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.
41app.include_router(auth_router)43app.include_router(auth_router)
42-# Heartbeat endpoints. Same 404 fallback semantics when the heartbeat44+# 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).
44app.include_router(heartbeat_router)50app.include_router(heartbeat_router)
45# Cluster (distributed sync) endpoints. Opt-in: every route 404s until the51# 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).
47app.include_router(cluster_router)53app.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 closed130 # 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_state132 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_event79 _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 event241 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 _service52 global _service
53- _service = RegistryService(database_dir, global_config_path)53+ _service = RegistryService(database_dir)
54 return _service54 return _service
55 55 
56 56 
@@ -64,7 +64,7 @@ def get_registry_service() -> RegistryService:
64async def _run(fn, *args):64async 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 
7import logging7import logging
8import time8import time
9+from typing import Optional
9 10 
10from a2x_registry.common.paths import database_dir11from a2x_registry.common.paths import database_dir
11from a2x_registry.common import feature_flags12from 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+ 
24def run_warmup() -> None:240def 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 logging242 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. Registry334 # 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 router337 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 caches467 # 2. Taxonomy caches
177- _stage("加载分类树...", 20)468+ _stage("Loading taxonomy tree...", 20)
178 from a2x_registry.backend.services.taxonomy_service import get_taxonomy_tree469 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 collections495 # 4. Clean stale ChromaDB collections
205- _stage("清理向量数据库...", 58)496+ _stage("Cleaning vector store...", 58)
206 try:497 try:
207 import chromadb498 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 datasets510 # 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 engines521 # 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"] = 100549 warmup_state["progress"] = 100
259 warmup_state["ready"] = True550 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 traceback554+ 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"] = True557 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_response4# - llm_client: LLMClient, LLMResponse, parse_json_response
5# - evaluation: compute_set_metrics5# - evaluation: compute_set_metrics
6# - naming: generate_output_dir6# - naming: generate_output_dir
7+# - log: DailyCompressedFileHandler
7 8 
8from .models import SearchResult9from .models import SearchResult
9from .llm_client import LLMClient, LLMResponse, parse_json_response10from .llm_client import LLMClient, LLMResponse, parse_json_response
10from .evaluation import compute_set_metrics11from .evaluation import compute_set_metrics
11from .naming import generate_output_dir12from .naming import generate_output_dir
13+from .log import DailyCompressedFileHandler
12from .errors import (14from .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).
20Web concerns live in ``deps.py`` / ``router.py``. The ``system_ctx`` module20Web concerns live in ``deps.py`` / ``router.py``. The ``system_ctx`` module
21provides the synthetic ``AuthContext`` the sweeper uses to call into21provides 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 
25from .errors import (30from .errors import (
@@ -30,7 +35,10 @@ from .errors import (
30from .models import HeartbeatLease, HBState35from .models import HeartbeatLease, HBState
31from .store import HeartbeatStore36from .store import HeartbeatStore
32from .sweeper import HeartbeatSweeper37from .sweeper import HeartbeatSweeper
33-from .deps import get_heartbeat_store, set_heartbeat_store38+from .deps import (
39+ get_heartbeat_store,
40+ set_heartbeat_store,
41+)
34from .system_ctx import SYSTEM_CTX42from .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, set3+Mirrors ``a2x_registry.auth.deps`` shape exactly - single global, set
4once at backend startup, returned by ``get_heartbeat_store()``. The4once at backend startup, returned by ``get_heartbeat_store()``. The
5-``None`` return path means "heartbeat module not initialized" — routers5+``None`` return path means "heartbeat module not initialized" - routers
6should fall back to permanent-service behavior in that case (matches6should 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 
10from __future__ import annotations13from __future__ import annotations
11 14 
15+import logging
12from typing import Optional16from typing import Optional
13 17 
14from .store import HeartbeatStore18from .store import HeartbeatStore
15 19 
20+logger = logging.getLogger(__name__)
21+ 
16_store: Optional[HeartbeatStore] = None22_store: Optional[HeartbeatStore] = None
17 23 
18 24 
@@ -12,6 +12,9 @@ Persisted state (``RegistryEntry.lease_ttl``) lives in the register
12module; the table only holds the **runtime** countdown state. Restart12module; the table only holds the **runtime** countdown state. Restart
13clears it; the store re-grants a grace-period lease for every entry whose13clears it; the store re-grants a grace-period lease for every entry whose
14persisted ``lease_ttl`` is non-empty (restart recovery).14persisted ``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 
17from __future__ import annotations20from __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}/heartbeat5 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}/heartbeat10 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 starts13 permanent=false: mark unhealthy, grace window starts
14 permanent=true: hard-delete via RegistryService (same path as14 permanent=true: hard-delete via RegistryService (same path as
15 an admin DELETE /services/{sid})15 an admin DELETE /services/{sid})
16 16 
17Both endpoints respect ``Depends(authorize)`` for namespace + auth17Both endpoints respect ``Depends(authorize)`` for namespace + auth
18checks (mirrors the existing reservation endpoints in dataset.py).18checks (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 
21from __future__ import annotations27from __future__ import annotations
22 28 
23import logging29import logging
30+import time as _t
24from typing import Optional31from typing import Optional
25 32 
26from fastapi import APIRouter, Depends, HTTPException33from 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 shared1+"""HeartbeatStore - per-namespace lease tracking on top of the shared
2``LeaseTable`` state machine.2``LeaseTable`` state machine.
3 3 
4Pure runtime store: no disk I/O, no FastAPI. The corresponding persisted4Pure 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
7at backend startup; the sweeper invokes ``RegistryService.deregister``7at backend startup; the sweeper invokes ``RegistryService.deregister``
8through the synthetic ``SYSTEM_CTX`` for hard deletion.8through the synthetic ``SYSTEM_CTX`` for hard deletion.
9 9 
10-This module owns the heartbeat-specific concerns — the per-namespace10+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 -
12and delegates the actual lease countdown / state transitions to12and 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 
16from __future__ import annotations20from __future__ import annotations
@@ -18,7 +22,7 @@ from __future__ import annotations
18import logging22import logging
19from typing import List, Optional, Tuple23from typing import List, Optional, Tuple
20 24 
21-from a2x_registry.common.lease import LeaseTable25+from a2x_registry.common.lease import Lease, LeaseState, LeaseTable
22 26 
23from .errors import (27from .errors import (
24 HeartbeatNotSupportedError,28 HeartbeatNotSupportedError,
@@ -30,7 +34,7 @@ from .models import HeartbeatLease
30logger = logging.getLogger(__name__)34logger = logging.getLogger(__name__)
31 35 
32 36 
33-# (dataset, service_id) → HeartbeatLease37+# (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 
3Single daemon thread, period configurable (default 5s). Each tick calls3Single daemon thread, period configurable (default 5s). Each tick calls
4``HeartbeatStore.sweep_tick()`` to get the lists of newly-unhealthy and4``HeartbeatStore.sweep_tick()`` to get the lists of newly-unhealthy and
5to-hard-delete sids, then invokes ``RegistryService.deregister`` for the5to-hard-delete sids, then invokes ``RegistryService.deregister`` for the
6-latter (using the synthetic ``SYSTEM_CTX`` — same code path as6+latter (using the synthetic ``SYSTEM_CTX`` - same code path as
7admin-initiated DELETE, so cache invalidation / file rewrite / vector7admin-initiated DELETE, so cache invalidation / file rewrite / vector
8sync all fire as expected).8sync all fire as expected).
9 9 
10Tests can either drive ``store.sweep_tick`` directly (synchronous,10Tests 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 
15from __future__ import annotations18from __future__ import annotations
@@ -17,9 +20,9 @@ from __future__ import annotations
17import logging20import logging
18import threading21import threading
19import time22import time
20-from typing import TYPE_CHECKING23+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__
23from .store import HeartbeatStore26from .store import HeartbeatStore
24from .system_ctx import SYSTEM_CTX27from .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 — defensive103+ 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]