diff --git a/README.md b/README.md index 7e4eb57..106462f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## 从这里开始 -先阅读 [Ubuntu 22.04 本地部署运行手册](docs/DEPLOYMENT-RUNBOOK.md)、[后端本地部署](docs/BACKEND-DEPLOYMENT.md)、[平台前端本地部署](docs/FRONTEND-DEPLOYMENT.md)、[管理端本地部署](docs/ADMIN-DEPLOYMENT.md)、[样机硬件评估报告](docs/POC-HARDWARE-BASELINE.md) 和 [源码版本核对](docs/SOURCE-RECONCILIATION.md)。当前可以启动 PostgreSQL、Redis、MinIO、平台后端、平台前端和 AI SoulMate 管理端;统一网关仍在后续阶段。 +先阅读 [Ubuntu 22.04 本地部署运行手册](docs/DEPLOYMENT-RUNBOOK.md)、[后端本地部署](docs/BACKEND-DEPLOYMENT.md)、[平台前端本地部署](docs/FRONTEND-DEPLOYMENT.md)、[管理端本地部署](docs/ADMIN-DEPLOYMENT.md)、[Tripo 零积分压测方案](docs/TRIPO-ZERO-COST-BENCHMARK.md)、[样机硬件评估报告](docs/POC-HARDWARE-BASELINE.md) 和 [源码版本核对](docs/SOURCE-RECONCILIATION.md)。当前可以启动 PostgreSQL、Redis、MinIO、平台后端、平台前端和 AI SoulMate 管理端;统一网关仍在后续阶段。 本仓库是 AI SoulMate 私有化部署的编排与留档仓库,用于固定源码版本、记录硬件基线、建设部署配置并沉淀压测结果。业务源码仍保留在各自仓库中,不复制源码、不改写原有 Git 历史。 @@ -10,7 +10,7 @@ - 当前 HP ZCentral 4R 样机适合做单机适配、功能跑通和容量边界测试,不作为生产高可用样板。 - 第一阶段在中心服务器部署平台后端、平台前端、AI SoulMate 管理端、PostgreSQL、Redis、本地对象存储和统一网关。 -- Tripo 暂时继续走外部 API,因此这是“业务数据和基础设施本地化”,不是完全离线部署。 +- Tripo 生产生成仍走外部 API,因此这是“业务数据和基础设施本地化”,不是完全离线部署;本地性能测试使用零外连、零积分的 `mock` 模式。 - 农场端 `ai-soulmate-client` 暂不部署到中心服务器,后续放到靠近打印机的工作站。 - 网关能力是必需的,但现有 `nginx-server` 的公网域名和固定路由不能原样交付,需要在本仓库形成私有部署配置。 diff --git a/benchmark/run-http-benchmark.py b/benchmark/run-http-benchmark.py new file mode 100644 index 0000000..7b5117f --- /dev/null +++ b/benchmark/run-http-benchmark.py @@ -0,0 +1,175 @@ +#!/usr/bin/env python3 +import argparse +import concurrent.futures +import datetime +import ipaddress +import json +import math +import pathlib +import socket +import statistics +import time +import urllib.error +import urllib.parse +import urllib.request + + +class NoRedirectHandler(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + return None + + +def parse_args(): + parser = argparse.ArgumentParser(description="Run a bounded HTTP benchmark against a local service.") + parser.add_argument("--url", required=True) + parser.add_argument("--method", default="GET", choices=("GET", "HEAD", "POST")) + parser.add_argument("--requests", type=int, default=100) + parser.add_argument("--concurrency", type=int, default=1) + parser.add_argument("--timeout", type=float, default=10.0) + parser.add_argument("--warmup", type=int, default=0) + parser.add_argument("--expected-status", type=int, action="append") + parser.add_argument("--body-file") + parser.add_argument("--headers-file") + parser.add_argument("--output") + return parser.parse_args() + + +def validate_target(raw_url): + parsed = urllib.parse.urlsplit(raw_url) + if parsed.scheme not in {"http", "https"} or not parsed.hostname: + raise ValueError("URL must use http or https and include a host.") + if parsed.username or parsed.password or parsed.query or parsed.fragment: + raise ValueError("Credentials, query strings, and fragments are not allowed in benchmark URLs.") + if parsed.hostname == "localhost": + return + try: + addresses = {item[4][0] for item in socket.getaddrinfo(parsed.hostname, parsed.port)} + except socket.gaierror as exc: + raise ValueError(f"Unable to resolve benchmark host: {parsed.hostname}") from exc + for address in addresses: + candidate = ipaddress.ip_address(address) + if not (candidate.is_loopback or candidate.is_private or candidate.is_link_local): + raise ValueError(f"Refusing to benchmark non-local address: {address}") + + +def percentile(values, percentage): + if not values: + return None + ordered = sorted(values) + rank = max(1, math.ceil((percentage / 100) * len(ordered))) + return round(ordered[rank - 1], 3) + + +def main(): + args = parse_args() + if not 1 <= args.requests <= 1_000_000: + raise SystemExit("--requests must be between 1 and 1000000") + if not 1 <= args.concurrency <= 256: + raise SystemExit("--concurrency must be between 1 and 256") + if args.warmup < 0 or args.timeout <= 0: + raise SystemExit("--warmup must be non-negative and --timeout must be positive") + + validate_target(args.url) + body = pathlib.Path(args.body_file).read_bytes() if args.body_file else None + headers = {} + if args.headers_file: + headers = json.loads(pathlib.Path(args.headers_file).read_text(encoding="utf-8")) + if not isinstance(headers, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in headers.items()): + raise SystemExit("--headers-file must contain a JSON object of string values") + + expected_statuses = set(args.expected_status or range(200, 400)) + opener = urllib.request.build_opener( + urllib.request.ProxyHandler({}), + NoRedirectHandler(), + ) + + def request_once(): + request = urllib.request.Request(args.url, data=body, headers=headers, method=args.method) + started = time.perf_counter() + try: + with opener.open(request, timeout=args.timeout) as response: + response_body = response.read() + retry_after = response.headers.get("Retry-After") + return response.status, (time.perf_counter() - started) * 1000, None, response_body, retry_after + except urllib.error.HTTPError as exc: + response_body = exc.read() + retry_after = exc.headers.get("Retry-After") + return exc.code, (time.perf_counter() - started) * 1000, None, response_body, retry_after + except Exception as exc: + return None, (time.perf_counter() - started) * 1000, type(exc).__name__, b"", None + + for _ in range(args.warmup): + request_once() + + started_at = datetime.datetime.now(datetime.timezone.utc) + started = time.perf_counter() + with concurrent.futures.ThreadPoolExecutor(max_workers=args.concurrency) as executor: + results = list(executor.map(lambda _: request_once(), range(args.requests))) + duration_seconds = time.perf_counter() - started + + latencies = [latency for _, latency, _, _, _ in results] + statuses = {} + errors = {} + response_codes = {} + retry_after_values = {} + successful = 0 + for status, _, error, response_body, retry_after in results: + if status is not None: + statuses[str(status)] = statuses.get(str(status), 0) + 1 + if status in expected_statuses: + successful += 1 + if error: + errors[error] = errors.get(error, 0) + 1 + if retry_after: + retry_after_values[retry_after] = retry_after_values.get(retry_after, 0) + 1 + if response_body: + try: + parsed_body = json.loads(response_body) + except (UnicodeDecodeError, json.JSONDecodeError): + parsed_body = None + if isinstance(parsed_body, dict) and parsed_body.get("code") is not None: + code = str(parsed_body["code"]) + response_codes[code] = response_codes.get(code, 0) + 1 + + report = { + "schema_version": 1, + "started_at_utc": started_at.isoformat(), + "target": args.url, + "method": args.method, + "requests": args.requests, + "concurrency": args.concurrency, + "timeout_seconds": args.timeout, + "warmup_requests": args.warmup, + "body_bytes": len(body or b""), + "custom_headers_supplied": bool(headers), + "duration_seconds": round(duration_seconds, 6), + "requests_per_second": round(args.requests / duration_seconds, 3), + "successful_requests": successful, + "failed_requests": args.requests - successful, + "status_counts": statuses, + "transport_error_counts": errors, + "application_code_counts": response_codes, + "retry_after_counts": retry_after_values, + "latency_ms": { + "min": round(min(latencies), 3), + "mean": round(statistics.fmean(latencies), 3), + "p50": percentile(latencies, 50), + "p95": percentile(latencies, 95), + "p99": percentile(latencies, 99), + "max": round(max(latencies), 3), + }, + } + + rendered = json.dumps(report, ensure_ascii=False, indent=2) + print(rendered) + if args.output: + output_path = pathlib.Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + output_path.write_text(rendered + "\n", encoding="utf-8") + + if successful != args.requests: + raise SystemExit(2) + + +if __name__ == "__main__": + main() diff --git a/benchmark/run-metadata.template.yml b/benchmark/run-metadata.template.yml index 84c4b08..d12fc65 100644 --- a/benchmark/run-metadata.template.yml +++ b/benchmark/run-metadata.template.yml @@ -13,11 +13,30 @@ hardware_profile: software: deployment_commit: "" - server_commit: "24769465d3ac2cb840c5266c8c0def2aacb641aa" - admin_commit: "40bd686128010fbbc6c33f6156a7a3cda5336b3a" + server_commit: "" + admin_commit: "" client_commit: null image_digests: {} database_migration: "" + tripo_mode: "mock" + external_paid_calls_allowed: false + +tripo_mock: + profile: "replace-with-compose-env-value" + api_generation: "v2-poc" + account_usage_tier: "unknown" + source_url: "https://developers.tripo3d.com/zh/docs/rate-limits" + source_checked_at: "2026-08-12" + account_concurrency: + h_series_3d: 10 + p_series_3d: 5 + image_generation: 1 + animation: 10 + model_postprocess: 5 + mesh_operations: 10 + queue_delay_seconds: 2 + run_delay_seconds: 8 + local_application_queue_enabled: false workload: scenario_id: "" @@ -27,12 +46,13 @@ workload: request_mix: {} object_sizes: [] includes_tripo: false + uses_tripo_mock: true configuration: application_profile: "" container_limits: {} database_pool_size: null - worker_count: null + worker_count: 1 changed_parameters: [] result: @@ -49,4 +69,3 @@ result: artifacts: raw_directory: "" report_path: "" - diff --git a/benchmark/run-user-e2e-smoke.py b/benchmark/run-user-e2e-smoke.py new file mode 100644 index 0000000..f707b8d --- /dev/null +++ b/benchmark/run-user-e2e-smoke.py @@ -0,0 +1,345 @@ +#!/usr/bin/env python3 +import argparse +import datetime +import ipaddress +import json +import pathlib +import secrets +import socket +import time +import urllib.error +import urllib.parse +import urllib.request + + +MAX_RESPONSE_BYTES = 2 * 1024 * 1024 +TERMINAL_STATUSES = {"COMPLETED", "FAILED", "CANCELLED"} + + +class NoRedirectHandler(urllib.request.HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + return None + + +class SmokeFailure(RuntimeError): + pass + + +def parse_args(): + parser = argparse.ArgumentParser( + description="Run one zero-credit user registration and text-to-3D smoke flow." + ) + parser.add_argument("--base-url", default="http://127.0.0.1:3001") + parser.add_argument("--timeout", type=float, default=10.0) + parser.add_argument("--poll-interval", type=float, default=1.0) + parser.add_argument("--deadline", type=float, default=90.0) + parser.add_argument("--output") + return parser.parse_args() + + +def private_addresses(hostname, port): + if hostname == "localhost": + return [ipaddress.ip_address("127.0.0.1")] + try: + return [ + ipaddress.ip_address(item[4][0]) + for item in socket.getaddrinfo(hostname, port, type=socket.SOCK_STREAM) + ] + except (socket.gaierror, ValueError) as exc: + raise SmokeFailure(f"Unable to resolve local target host: {hostname}") from exc + + +def is_private_address(address): + return address.is_loopback or address.is_private or address.is_link_local + + +def validate_base_url(raw_url): + parsed = urllib.parse.urlsplit(raw_url) + if parsed.scheme not in {"http", "https"} or not parsed.hostname: + raise SmokeFailure("Base URL must use http or https and include a host.") + if parsed.username or parsed.password or parsed.query or parsed.fragment: + raise SmokeFailure("Credentials, query strings, and fragments are forbidden in the base URL.") + if parsed.path not in {"", "/"}: + raise SmokeFailure("Base URL must not include an API path.") + addresses = private_addresses(parsed.hostname, parsed.port) + if not addresses or any(not is_private_address(address) for address in addresses): + raise SmokeFailure("Refusing to run the smoke flow against a non-local address.") + return raw_url.rstrip("/") + + +def read_json_response(response): + raw_body = response.read(MAX_RESPONSE_BYTES + 1) + if len(raw_body) > MAX_RESPONSE_BYTES: + raise SmokeFailure("Server response exceeded the 2 MiB safety limit.") + try: + payload = json.loads(raw_body.decode("utf-8")) + except (UnicodeDecodeError, json.JSONDecodeError) as exc: + raise SmokeFailure("Server returned a non-JSON response.") from exc + if not isinstance(payload, dict): + raise SmokeFailure("Server returned a non-object JSON response.") + return payload + + +def storage_location(raw_url): + value = str(raw_url or "").strip() + result = {"present": bool(value), "scheme": None, "host": None, "local": False} + if not value: + return result + if value.startswith("oss://") or value.startswith("models/"): + result.update({"scheme": "oss", "host": "internal", "local": True}) + return result + parsed = urllib.parse.urlsplit(value) + result["scheme"] = parsed.scheme or "relative" + result["host"] = parsed.hostname + if parsed.scheme not in {"http", "https"} or not parsed.hostname: + return result + if "tripo" in parsed.hostname.lower(): + return result + try: + addresses = private_addresses(parsed.hostname, parsed.port) + except SmokeFailure: + return result + result["local"] = bool(addresses) and all(is_private_address(address) for address in addresses) + return result + + +class LocalApi: + def __init__(self, base_url, timeout): + self.base_url = base_url + self.timeout = timeout + self.opener = urllib.request.build_opener( + urllib.request.ProxyHandler({}), NoRedirectHandler() + ) + + def request(self, method, path, body=None, bearer=None): + if not path.startswith("/"): + raise SmokeFailure("Internal request path must start with a slash.") + headers = { + "Accept": "application/json", + "User-Agent": "ai-soulmate-zero-credit-smoke/1", + } + data = None + if body is not None: + data = json.dumps(body, separators=(",", ":")).encode("utf-8") + headers["Content-Type"] = "application/json" + if bearer: + headers["Authorization"] = f"Bearer {bearer}" + request = urllib.request.Request( + self.base_url + path, data=data, headers=headers, method=method + ) + started = time.perf_counter() + try: + with self.opener.open(request, timeout=self.timeout) as response: + if not 200 <= response.status < 300: + raise SmokeFailure(f"{method} {path} returned HTTP {response.status}.") + return response.status, read_json_response(response), round( + (time.perf_counter() - started) * 1000, 3 + ) + except urllib.error.HTTPError as exc: + exc.close() + raise SmokeFailure(f"{method} {path} returned HTTP {exc.code}.") from exc + except (urllib.error.URLError, TimeoutError, OSError) as exc: + raise SmokeFailure(f"{method} {path} failed at the transport layer.") from exc + + +def numeric_credits(payload): + value = payload.get("credits") + if isinstance(value, bool) or not isinstance(value, (int, float)): + raise SmokeFailure("User profile did not contain numeric credits.") + return int(value) + + +def write_report(report, output): + rendered = json.dumps(report, ensure_ascii=False, indent=2) + print(rendered) + if output: + output_path = pathlib.Path(output) + output_path.parent.mkdir(parents=True, exist_ok=True) + output_path.write_text(rendered + "\n", encoding="utf-8") + + +def main(): + args = parse_args() + if args.timeout <= 0 or args.poll_interval <= 0 or args.deadline <= 0: + raise SystemExit("Timeout, poll interval, and deadline must be positive.") + if args.timeout > 60 or args.deadline > 600: + raise SystemExit("Timeout must be at most 60 seconds and deadline at most 600 seconds.") + + started_at = datetime.datetime.now(datetime.timezone.utc) + report = { + "schema_version": 1, + "started_at_utc": started_at.isoformat(), + "base_url": None, + "valid": False, + "zero_credit_verified": False, + "local_storage_verified": False, + "steps": {}, + } + current_step = "validate_target" + try: + base_url = validate_base_url(args.base_url) + report["base_url"] = base_url + api = LocalApi(base_url, args.timeout) + + current_step = "verify_mock_mode" + health_status, health, health_ms = api.request("GET", "/api/health") + tripo_mode = str(health.get("tripo_mode") or "").strip().lower() + mock_profile = str(health.get("tripo_mock_profile") or "").strip() + report["steps"]["verify_mock_mode"] = { + "http_status": health_status, + "latency_ms": health_ms, + "service_status": health.get("status"), + "tripo_mode": tripo_mode, + "tripo_mock_profile": mock_profile, + } + if tripo_mode != "mock" or not mock_profile or mock_profile == "not-selected": + raise SmokeFailure("Backend health did not confirm an explicit Tripo mock profile.") + + username = f"bench_{int(time.time())}_{secrets.token_hex(4)}" + password = "Bm!9" + secrets.token_urlsafe(18) + current_step = "register" + register_status, registration, register_ms = api.request( + "POST", + "/api/auth/register", + { + "username": username, + "password": password, + "password_confirm": password, + "register_via": "account", + }, + ) + token = registration.get("access_token") + user = registration.get("user") + if not isinstance(token, str) or not token or not isinstance(user, dict): + raise SmokeFailure("Registration response omitted the access token or user object.") + user_id = str(user.get("id") or "") + if not user_id: + raise SmokeFailure("Registration response omitted the user ID.") + report["steps"]["register"] = { + "http_status": register_status, + "latency_ms": register_ms, + "user_id": user_id, + } + + current_step = "profile_before" + profile_status, profile_before, profile_before_ms = api.request( + "GET", "/api/user/profile", bearer=token + ) + credits_before = numeric_credits(profile_before) + report["steps"]["profile_before"] = { + "http_status": profile_status, + "latency_ms": profile_before_ms, + "credits": credits_before, + "assets_count": profile_before.get("assets_count"), + } + + current_step = "submit" + submit_status, submitted, submit_ms = api.request( + "POST", + "/api/studio/submit-text-3d", + { + "prompt": "A small geometric calibration object for local benchmark validation", + "with_texture": True, + "model_version": "v3.1-20260211", + "render_image": True, + "result_format": "GLB", + }, + bearer=token, + ) + job_id = str(submitted.get("job_id") or "") + if not job_id: + raise SmokeFailure("Submission response omitted the job ID.") + submit_credits = submitted.get("credits_used") + report["steps"]["submit"] = { + "http_status": submit_status, + "latency_ms": submit_ms, + "job_id": job_id, + "credits_used": submit_credits, + } + + current_step = "poll_job" + polling_started = time.monotonic() + observations = [] + poll_count = 0 + terminal = None + last_poll_ms = None + while time.monotonic() - polling_started < args.deadline: + _, polled, last_poll_ms = api.request( + "GET", f"/api/studio/job/{urllib.parse.quote(job_id, safe='')}", bearer=token + ) + poll_count += 1 + status_name = str(polled.get("status") or "UNKNOWN").upper() + if not observations or observations[-1]["status"] != status_name: + observations.append( + { + "status": status_name, + "elapsed_seconds": round(time.monotonic() - polling_started, 3), + } + ) + if status_name in TERMINAL_STATUSES: + terminal = polled + break + time.sleep(args.poll_interval) + if terminal is None: + raise SmokeFailure("Job did not reach a terminal state before the deadline.") + if str(terminal.get("status") or "").upper() != "COMPLETED": + raise SmokeFailure("Job reached a non-success terminal state.") + + model_storage = storage_location( + terminal.get("selected_model_url") or terminal.get("model_url") + ) + preview_storage = storage_location(terminal.get("preview_url")) + terminal_credits = terminal.get("credits_used") + report["steps"]["poll_job"] = { + "poll_count": poll_count, + "duration_seconds": round(time.monotonic() - polling_started, 3), + "last_poll_latency_ms": last_poll_ms, + "status_observations": observations, + "terminal_status": terminal.get("status"), + "credits_used": terminal_credits, + "asset_id": terminal.get("asset_id"), + "model_storage": model_storage, + "preview_storage": preview_storage, + } + + current_step = "profile_after" + profile_after_status, profile_after, profile_after_ms = api.request( + "GET", "/api/user/profile", bearer=token + ) + credits_after = numeric_credits(profile_after) + report["steps"]["profile_after"] = { + "http_status": profile_after_status, + "latency_ms": profile_after_ms, + "credits": credits_after, + "credits_delta": credits_after - credits_before, + "assets_count": profile_after.get("assets_count"), + } + + report["zero_credit_verified"] = ( + submit_credits == 0 and terminal_credits == 0 and credits_after == credits_before + ) + report["local_storage_verified"] = ( + model_storage["present"] + and model_storage["local"] + and preview_storage["present"] + and preview_storage["local"] + ) + report["valid"] = report["zero_credit_verified"] and report["local_storage_verified"] + if not report["zero_credit_verified"]: + raise SmokeFailure("The business flow did not preserve the user's credit balance.") + if not report["local_storage_verified"]: + raise SmokeFailure("The completed job did not return local model and preview storage.") + except SmokeFailure as exc: + report["failed_step"] = current_step + report["error"] = str(exc) + + report["duration_seconds"] = round( + (datetime.datetime.now(datetime.timezone.utc) - started_at).total_seconds(), 3 + ) + write_report(report, args.output) + if not report["valid"]: + raise SystemExit(2) + + +if __name__ == "__main__": + main() diff --git a/benchmark/summarize-http-results.py b/benchmark/summarize-http-results.py new file mode 100644 index 0000000..3af6aaf --- /dev/null +++ b/benchmark/summarize-http-results.py @@ -0,0 +1,51 @@ +#!/usr/bin/env python3 +import argparse +import json +import pathlib + + +def main(): + parser = argparse.ArgumentParser(description="Summarize HTTP benchmark JSON files as Markdown.") + parser.add_argument("directory") + parser.add_argument("--output") + args = parser.parse_args() + + directory = pathlib.Path(args.directory) + rows = [] + for path in sorted(directory.glob("*.json")): + payload = json.loads(path.read_text(encoding="utf-8")) + latency = payload.get("latency_ms") or {} + rows.append( + ( + path.stem, + payload.get("concurrency"), + payload.get("requests"), + payload.get("successful_requests"), + payload.get("failed_requests"), + payload.get("requests_per_second"), + latency.get("p50"), + latency.get("p95"), + latency.get("p99"), + latency.get("max"), + ) + ) + + if not rows: + raise SystemExit(f"No benchmark JSON files found in: {directory}") + + lines = [ + "| 场景 | 并发 | 请求数 | 成功 | 失败 | RPS | P50 ms | P95 ms | P99 ms | 最大 ms |", + "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |", + ] + for row in rows: + lines.append("| " + " | ".join(str(value) for value in row) + " |") + rendered = "\n".join(lines) + "\n" + print(rendered, end="") + if args.output: + output_path = pathlib.Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + output_path.write_text(rendered, encoding="utf-8") + + +if __name__ == "__main__": + main() diff --git a/compose/.env.example b/compose/.env.example index 154e986..7e57f68 100644 --- a/compose/.env.example +++ b/compose/.env.example @@ -40,6 +40,8 @@ FRONTEND_BIND_ADDRESS=127.0.0.1 FRONTEND_HOST_PORT=8080 FRONTEND_MEMORY_LIMIT=1g FRONTEND_CPU_LIMIT=1.0 +TRIPO3D_MODE=disabled +TRIPO3D_MOCK_PROFILE=not-selected ADMIN_COMPOSE_PROJECT_NAME=ai-soulmate-admin ADMIN_BACKEND_IMAGE=ai-soulmate-admin-backend:replace-with-source-commit @@ -78,3 +80,12 @@ FRONTEND_URL=http://127.0.0.1:8080 TRIPO3D_API_KEY= TRIPO3D_BASE_URL=https://api.tripo3d.com/v2/openapi TRIPO3D_DEFAULT_MODEL_VERSION=v3.1-20260211 +TRIPO3D_MOCK_QUEUE_DELAY_SECONDS=2 +TRIPO3D_MOCK_RUN_DELAY_SECONDS=8 +TRIPO3D_MOCK_H_CONCURRENCY=10 +TRIPO3D_MOCK_P_CONCURRENCY=5 +TRIPO3D_MOCK_IMAGE_CONCURRENCY=1 +TRIPO3D_MOCK_ANIMATION_CONCURRENCY=10 +TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY=5 +TRIPO3D_MOCK_MESH_CONCURRENCY=10 +TRIPO3D_MOCK_TASK_RETENTION_SECONDS=3600 diff --git a/compose/docker-compose.backend.yml b/compose/docker-compose.backend.yml index f2690d5..75180e6 100644 --- a/compose/docker-compose.backend.yml +++ b/compose/docker-compose.backend.yml @@ -27,9 +27,20 @@ services: CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:?CORS_ALLOWED_ORIGINS is required} AI_SOULMATE_PUBLIC_URL: ${AI_SOULMATE_PUBLIC_URL:?AI_SOULMATE_PUBLIC_URL is required} FRONTEND_URL: ${FRONTEND_URL:?FRONTEND_URL is required} + TRIPO3D_MODE: ${TRIPO3D_MODE:-disabled} + TRIPO3D_MOCK_PROFILE: ${TRIPO3D_MOCK_PROFILE:-not-selected} TRIPO3D_API_KEY: ${TRIPO3D_API_KEY:-} TRIPO3D_BASE_URL: ${TRIPO3D_BASE_URL:-https://api.tripo3d.com/v2/openapi} TRIPO3D_DEFAULT_MODEL_VERSION: ${TRIPO3D_DEFAULT_MODEL_VERSION:-v3.1-20260211} + TRIPO3D_MOCK_QUEUE_DELAY_SECONDS: ${TRIPO3D_MOCK_QUEUE_DELAY_SECONDS:-2} + TRIPO3D_MOCK_RUN_DELAY_SECONDS: ${TRIPO3D_MOCK_RUN_DELAY_SECONDS:-8} + TRIPO3D_MOCK_H_CONCURRENCY: ${TRIPO3D_MOCK_H_CONCURRENCY:-10} + TRIPO3D_MOCK_P_CONCURRENCY: ${TRIPO3D_MOCK_P_CONCURRENCY:-5} + TRIPO3D_MOCK_IMAGE_CONCURRENCY: ${TRIPO3D_MOCK_IMAGE_CONCURRENCY:-1} + TRIPO3D_MOCK_ANIMATION_CONCURRENCY: ${TRIPO3D_MOCK_ANIMATION_CONCURRENCY:-10} + TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY: ${TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY:-5} + TRIPO3D_MOCK_MESH_CONCURRENCY: ${TRIPO3D_MOCK_MESH_CONCURRENCY:-10} + TRIPO3D_MOCK_TASK_RETENTION_SECONDS: ${TRIPO3D_MOCK_TASK_RETENTION_SECONDS:-3600} PAYMENT_V2_ENABLED: "false" ALLOW_DEV_VERIFICATION_CODE_RESPONSE: "false" UPLOAD_DIR: /app/uploads diff --git a/docs/TRIPO-ZERO-COST-BENCHMARK.md b/docs/TRIPO-ZERO-COST-BENCHMARK.md new file mode 100644 index 0000000..e7a9519 --- /dev/null +++ b/docs/TRIPO-ZERO-COST-BENCHMARK.md @@ -0,0 +1,191 @@ +# Tripo 零积分软硬件适配压测方案 + +## 1. 目的 + +本方案用于在不调用 Tripo 真实生成接口、不消耗 Tripo 生成积分的前提下,验证 AI SoulMate 用户端、管理端、中心服务器和 Client 农场端在当前软硬件环境中的性能、稳定性与任务排队行为。 + +本阶段使用后端内置的 `mock` 模式模拟 Tripo 任务生命周期。该模式不会向 Tripo 或其他 Tripo 地址发送网络请求,模拟任务的本地平台计费为 0,因此暂时不需要配置或更换 Tripo API key。只有进入真实 Tripo 联调阶段时才需要 API key,并应先用少量请求验证账户额度与实际限制。 + +部署时必须显式选择 `rate-limits-page` 或 `model-pages-conservative` profile,选择值和六类并发配置要随每次测试结果一起留档。当前实现只承诺生成提交与任务查询不会调用 Tripo;历史任务中的 Tripo 外链代理属于另一条读取链路,不能把“零生成计费调用”扩大解释成“容器绝无任何公网数据包”。正式压测会避开历史外链代理,并单独记录网络边界。 + +## 2. 测试边界 + +本轮包括: + +- AI SoulMate 用户端、管理端及其后端接口。 +- 中心服务器上的 PostgreSQL、Redis、MinIO 和 Docker 容器。 +- Client 工作站上的前端、后端、独立 PostgreSQL,以及与中心服务器之间的心跳和任务同步链路。 +- Tripo `mock` 模式下的任务提交、状态流转、结果落入 MinIO、并发拒绝及本地队列行为。 + +本轮不包括: + +- Tripo 真实模型生成、真实计费、真实公网延迟和真实上游模型耗时。 +- 阿里云提示词翻译、提示词优化等其他云服务。压测请求必须绕过或关闭这些外部调用,避免产生费用,也避免其网络波动污染本地基线。 +- 快造 U1 的 PIN 配对、动态 IP 发现和真实打印。打印机接入在平台基线稳定后单独测试。 + +因此,本轮结果只能说明本地平台与当前硬件的承载能力,不能直接等同于 Tripo 的真实生成吞吐量。 + +## 3. Tripo 官方限制与本地配置 + +Tripo 的请求速率限制按 API key 计算;任务并发限制按账户及任务类别计算,不是整个系统共用一个固定并发数。根据 [Tripo 官方速率限制与并发控制文档](https://developers.tripo3d.com/zh/docs/rate-limits),专门限流页在 2026-08-12 显示的默认基线如下: + +| 任务类别 | 官方页面当前公开并发数 | 本地 mock 配置项 | +| --- | ---: | --- | +| H 系列 3D 生成 | 10 | `TRIPO3D_MOCK_H_CONCURRENCY` | +| P 系列 3D 生成 | 5 | `TRIPO3D_MOCK_P_CONCURRENCY` | +| 图像生成 | 1 | `TRIPO3D_MOCK_IMAGE_CONCURRENCY` | +| 动画 | 10 | `TRIPO3D_MOCK_ANIMATION_CONCURRENCY` | +| 模型后处理 | 5 | `TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY` | +| 网格操作 | 10 | `TRIPO3D_MOCK_MESH_CONCURRENCY` | + +这些值只是本次 v2 POC 测试 profile 的默认基线,不是当前账户合同额度。官方 H3.1、P1 和 Animation 模型详情页又分别显示 `3` 个并行任务,并说明额度取决于用量层级;这可能涉及 API 版本、模型或套餐口径差异。正式联调时必须以当前官方文档、账户实际配额以及接口真实返回为准。本地 mock 的各类别并发配置均可调整,用于复现不同客户方案或账户等级,不能把某次配置值写成产品的永久上限;迁移到 v3 API 时应另建 profile,并优先用保守的 `3` 并发做首次验证。 + +Tripo 的“请求速率限制”和“运行任务并发限制”也不是同一概念。上游任务并发达到限制时,官方接口可能返回 HTTP `429`、业务码 `2000`,并可能携带 `Retry-After`。调用方应记录并遵循 `Retry-After`,采用有限次数、带抖动的退避重试,不能无间隔循环请求。 + +官方页面没有声明一个适用于所有账户的固定最大排队长度。因此,本方案不假设、不报告“Tripo 最多可排队 N 个任务”。如需得出真实账户的上游并发或排队结论,应在获准使用积分后做小规模实测,并保留响应码、响应头、任务状态和时间戳作为依据。 + +## 4. 两层并发与队列必须分开 + +系统中至少存在两层不同的容量控制: + +1. **AI SoulMate 本地任务队列**:由本地应用、数据库和 Redis 管理。它决定平台能接收多少用户请求、任务等待多久、是否丢失或重复,以及 Client 农场端的同步速度。 +2. **Tripo 上游运行并发**:由 Tripo 按账户和任务类别控制。它决定同一类别能够同时在 Tripo 侧运行多少任务,超过限制可能直接得到 HTTP `429`、业务码 `2000`。 + +本地队列可以容纳的任务数不等于 Tripo 并发数;Tripo 某类别仍有空闲槽位也不代表本地服务器没有瓶颈。报告必须分别给出: + +- 本地接收量、队列深度、等待时间、出队速率和失败量。 +- 模拟的各类别上游活动任务数、被拒绝量、`429/2000` 数量和 `Retry-After`。 +- 两层之间的调度效率,例如上游有空位但本地任务未及时提交的时间占比。 + +## 5. Mock 模式的 POC 限制 + +当前 mock 任务状态保存在后端进程内存中,适合单进程 POC 和压测链路验证,但有以下限制: + +- 后端容器或进程重启后,未完成的 mock 任务状态会丢失。 +- 多后端副本之间不共享 mock 状态,不能据此验证正式集群的一致性。 +- mock 的等待时间和运行时间是配置值,不代表 Tripo 真实模型耗时。 +- mock 可以验证调度、结果上传和错误处理,但不能验证 Tripo 生成质量或公网服务稳定性。 + +正式多实例压测前,应把任务状态和并发租约迁移到 PostgreSQL 或 Redis,并增加幂等键、租约超时和崩溃恢复机制。在此之前,测试记录必须标记为“单后端进程 POC”。 + +## 6. 测试阶段 + +### 阶段 0:冻结环境与确认安全开关 + +- 记录三台设备的名称、IP、CPU、内存、磁盘、网络、操作系统、Docker/WSL 版本和源代码提交号。 +- 确认后端为 `TRIPO3D_MODE=mock`,健康接口返回的模式也是 `mock`。 +- 确认压测环境未配置可被当前流程使用的 Tripo API key,或通过网络日志确认没有 Tripo 外连。 +- 确认阿里云提示词翻译/优化不在测试请求路径中。 +- 保存数据库、Redis 和 MinIO 的可恢复备份。 + +在中心服务器部署新镜像后,必须按以下顺序启用并验证。`configure-backend-env.sh` 在 mode 已是 `mock` 时也会再次清空 API key 并恢复 loopback 阻断地址,避免重复配置误切回真实上游: + +```bash +./scripts/enable-tripo-mock.sh compose/.env rate-limits-page +./scripts/configure-backend-env.sh compose/.env /srv/ai-soulmate/sources/ai-soulmate-server 192.168.3.102 farm-workstation-001 +./scripts/enable-tripo-mock.sh compose/.env rate-limits-page +./scripts/build-backend-image.sh compose/.env /srv/ai-soulmate/sources/ai-soulmate-server +./scripts/build-frontend-image.sh compose/.env /srv/ai-soulmate/sources/ai-soulmate-server +./scripts/start-backend.sh compose/.env +./scripts/start-frontend.sh compose/.env +./scripts/verify-backend.sh compose/.env +./scripts/verify-frontend.sh compose/.env +./scripts/verify-tripo-mock.sh compose/.env +``` + +首次基线同时用 `model-pages-conservative` 再跑一次敏感性测试。切换 profile 只会修改 `.env`,不会自动改变已运行容器;切换后必须执行 `docker compose --project-name "$(sed -n 's/^BACKEND_COMPOSE_PROJECT_NAME=//p' compose/.env | head -n 1)" --env-file compose/.env -f compose/docker-compose.backend.yml up -d --force-recreate backend`,再运行 `verify-tripo-mock.sh`。每次执行都必须把实际 profile、六类并发、queue/run delay、源代码提交和镜像摘要写入运行元数据,不能直接沿用模板默认值。 + +### 阶段 1:空闲基线 + +- 在无业务流量状态连续采集至少 15 分钟。 +- 记录各设备和容器的 CPU、内存、磁盘、网络、进程数、连接数、重启次数和健康状态。 +- 得到后续负载测试的资源增量参照值。 + +### 阶段 2:基础接口与存储基线 + +- 分别测试用户端、管理端的健康检查、登录、列表查询、详情查询和静态资源。 +- 单独测试 PostgreSQL 查询、Redis 读写及 MinIO 小文件和模型文件上传/下载。 +- 先做单请求正确性检查,再逐级提升并发,避免错误请求形成无效高负载。 + +### 阶段 3:Tripo mock 单任务闭环 + +先运行公开用户端的零积分端到端冒烟测试。脚本只接受本机、私网或链路本地地址,禁用系统代理与 HTTP 重定向;它在内存中创建随机账号和密码,输出中不会写入密码或 Bearer token。测试会比较生成前后的用户积分、检查提交和完成结果的 `credits_used=0`,并确认模型和预览均指向本地对象存储: + +```bash +./scripts/run-user-e2e-smoke.sh compose/.env +``` + +每次执行会保留一个带 `bench_` 前缀的隔离测试用户、一个本地 mock 资产和对应任务记录,以便管理端核对。原始 JSON 只记录随机用户 ID、任务 ID、状态转换、耗时、积分数值和脱敏后的存储位置摘要,不记录账号密码、访问 token 或带签名参数的完整 MinIO URL。 + +- 每个任务类别至少完成一次提交、排队、运行、完成和结果读取。 +- 验证模拟模型/图片能够写入本地 MinIO,数据库任务状态、结果地址和本地积分均正确。 +- 验证失败任务、超时任务、重复请求和容器重启后的 POC 限制表现。 + +### 阶段 4:分类并发和拒绝行为 + +- 逐项验证 H、P、图像、动画、后处理和网格操作的独立并发池。 +- 在单类别内从 1 并发逐级增加到该类别配置上限,再增加 1 至 2 个请求验证 HTTP `429`、业务码 `2000` 和 `Retry-After`。 +- 同时运行两个不同类别,验证它们不会错误地占用同一个全局并发池。 +- 调整本地 mock 并发配置,复测不同客户配额场景并记录配置快照。 + +当前公开用户端可完整走通 H/P 3D 与图像生成路径;动画、后处理和网格操作尚无对应的公开业务提交接口。后 3 类只使用容器内 `tools/tripo_mock_benchmark.py` 验证分类池、状态时间、`429/2000` 和本地 MinIO 结果,不能表述为前端端到端能力。公开业务端到端报告应只统计实际可达的 H/P 3D 与图像链路。 + +### 阶段 5:本地排队与端到端链路 + +- 让进入平台的任务量高于模拟上游可运行量,观察本地队列深度、等待时间和退避重试。 +- 验证中心服务器到 Client 工作站的心跳、任务同步、领取、状态回传和断线恢复。 +- 检查任务是否出现丢失、重复领取、乱序完成或状态永久卡住。 +- 此阶段仅模拟“任务到达农场端”,不向快造 U1 发起真实打印。 + +### 阶段 6:阶梯负载与稳定性 + +- 使用固定测试数据,按低、中、高和饱和负载逐级增加并发,每级保持足够时间达到稳定状态。 +- 找出首次出现明显延迟陡升、错误率增长、队列持续积压或资源耗尽的负载点。 +- 在安全负载下做长时间稳定性测试,并验证服务重启、网络短时中断和恢复后的数据一致性。 +- 达到任一停止条件时立即停止增压,不以设备失去响应作为“极限值”。 + +当前自动 HTTP 套件只对用户后端与管理后端健康接口执行 `1/5/10/20/40` 阶梯并发,它用于测量框架、代理和基础数据库连通性开销,不代表登录、列表、生成或订单接口的业务容量。套件会把负载期间逐秒容器 CPU、内存、网络、磁盘 I/O、PID、主机 1 分钟负载和可用内存写入 `resources-during-load.csv`;最终客户容量结论仍必须补充带认证的业务接口和长时间稳定性测试。 + +### 阶段 7:打印机专项测试 + +平台基线和 mock 任务闭环稳定后,再接入快造 U1。打印机阶段单独记录 PIN 配对、IP 变化、发现机制、连接恢复、单机/多机并行打印和打印队列,不与本轮 Tripo mock 容量结论混合。 + +## 7. 必须采集的指标 + +| 层级 | 指标 | +| --- | --- | +| 请求 | 请求总数、成功数、吞吐量、错误率、超时率、HTTP 状态码分布、P50/P90/P95/P99/最大延迟 | +| 本地队列 | 入队速率、出队速率、当前/最大队列深度、平均/P95/最大等待时间、积压持续时间、丢失/重复任务数 | +| Tripo mock | 各类别活动任务数、配置上限、接受数、`429/2000` 数、`Retry-After` 值、重试次数、模拟运行时间 | +| 业务闭环 | 提交到完成总耗时、结果写入耗时、状态一致性、幂等命中、失败恢复、用户/管理端可见时间 | +| Client 链路 | 心跳成功率和延迟、任务同步延迟、领取/回传耗时、断线时长、恢复耗时、待处理任务数 | +| PostgreSQL | 活跃/等待连接、事务吞吐、查询延迟、慢查询、锁等待、死锁、缓存命中、数据库增长量 | +| Redis | 操作速率、连接数、内存、命中率、过期/淘汰键、阻塞客户端、队列相关键数量 | +| MinIO | 上传/下载吞吐、首字节和完成延迟、失败率、对象数、存储增长量、磁盘使用率 | +| 设备/容器 | CPU、内存、交换区、磁盘吞吐/延迟/空间、网络吞吐/丢包、容器重启、OOM、温度与降频(可获取时) | + +所有指标必须带统一时区的时间戳,并关联测试批次、代码提交、镜像摘要、环境配置、并发模型、请求数据集和测试持续时间。平均值不能代替尾延迟,报告至少保留 P95 和 P99。 + +## 8. 停止条件与结论口径 + +建议在出现以下任一情况时停止继续增压: + +- 持续错误率或超时率超过测试预先设定的阈值。 +- P95/P99 延迟连续多个采样窗口恶化且不能恢复。 +- 本地队列只增不减,已无法在合理时间内清空。 +- CPU 长时间饱和、内存接近耗尽、发生 OOM、磁盘空间不足或磁盘延迟异常。 +- 数据丢失、重复执行、状态不一致或关键服务反复重启。 + +最终报告应给出“稳定运行区间”“出现退化的起点”和“明确不可接受区间”,不要只给一个没有持续时间和错误率背景的最高并发数字。对外提供客户配置建议时,还应保留安全余量,并明确 Tripo 上游配额、真实生成耗时和打印机数量需要另行校准。 + +## 9. 进入真实 Tripo 联调的前置条件 + +只有在以下条件全部满足后才进入真实联调: + +- 本地用户端、管理端、中心基础设施和 Client 链路的基线测试通过。 +- mock 模式下的分类并发、拒绝、退避、本地排队和恢复行为符合预期。 +- 已确认实际 Tripo 账户的模型权限、套餐、余额和各类别并发配额。 +- 已设置严格的请求数量上限、预算上限和人工停止开关。 +- 已准备专用 API key,并保证它不会写入 Git、日志或测试报告。 + +届时先做最小数量的冒烟请求,再逐步扩大;不能直接用真实 API 执行本方案中的饱和压测。 diff --git a/scripts/capture-benchmark-snapshot.sh b/scripts/capture-benchmark-snapshot.sh new file mode 100755 index 0000000..e39cd42 --- /dev/null +++ b/scripts/capture-benchmark-snapshot.sh @@ -0,0 +1,79 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +infra_compose="${repo_root}/compose/docker-compose.infra.yml" +backend_compose="${repo_root}/compose/docker-compose.backend.yml" +admin_compose="${repo_root}/compose/docker-compose.admin.yml" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +section() { + printf '\n## %s\n' "$1" +} + +read_value() { + local key="$1" + sed -n "s/^${key}=//p" "$env_file" | head -n 1 +} + +infra_project="$(read_value COMPOSE_PROJECT_NAME)" +backend_project="$(read_value BACKEND_COMPOSE_PROJECT_NAME)" +admin_project="$(read_value ADMIN_COMPOSE_PROJECT_NAME)" + +if [[ -z "$infra_project" || -z "$backend_project" || -z "$admin_project" ]]; then + echo "Compose project names are missing from the environment file." >&2 + exit 1 +fi + +section "Runtime snapshot" +bash "${repo_root}/scripts/capture-runtime-snapshot.sh" + +section "Application containers" +docker compose --project-name "$infra_project" --env-file "$env_file" -f "$infra_compose" ps --all +docker compose --project-name "$backend_project" --env-file "$env_file" -f "$backend_compose" ps --all +docker compose --project-name "$admin_project" --env-file "$env_file" -f "$admin_compose" ps --all + +section "Container resource totals" +docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}\t{{.PIDs}}' + +section "PostgreSQL database statistics" +docker compose --project-name "$infra_project" --env-file "$env_file" -f "$infra_compose" exec -T postgres sh -ec ' +psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -P pager=off -c " +SELECT datname, + numbackends, + xact_commit, + xact_rollback, + blks_read, + blks_hit, + temp_files, + temp_bytes, + deadlocks, + pg_database_size(datname) AS size_bytes +FROM pg_stat_database +WHERE datname IN (current_database(), '\''mlkj_admin'\'') +ORDER BY datname;" +' + +section "PostgreSQL connection states" +docker compose --project-name "$infra_project" --env-file "$env_file" -f "$infra_compose" exec -T postgres sh -ec ' +psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -P pager=off -c " +SELECT datname, state, wait_event_type, count(*) +FROM pg_stat_activity +WHERE datname IS NOT NULL +GROUP BY datname, state, wait_event_type +ORDER BY datname, state, wait_event_type;" +' + +section "Redis statistics" +docker compose --project-name "$infra_project" --env-file "$env_file" -f "$infra_compose" exec -T redis sh -ec ' +redis-cli --no-auth-warning -a "$REDIS_PASSWORD" INFO clients memory stats persistence | + grep -E "^(connected_clients|blocked_clients|used_memory:|used_memory_peak:|mem_fragmentation_ratio:|total_connections_received:|total_commands_processed:|instantaneous_ops_per_sec:|keyspace_hits:|keyspace_misses:|evicted_keys:|expired_keys:|rdb_last_bgsave_status:|aof_enabled:)" +' + +section "Docker disk usage" +docker system df diff --git a/scripts/configure-backend-env.sh b/scripts/configure-backend-env.sh index b7fa6ec..fa40906 100755 --- a/scripts/configure-backend-env.sh +++ b/scripts/configure-backend-env.sh @@ -107,11 +107,49 @@ set_value OSS_PUBLIC_ENDPOINT "http://${public_host}:9000" set_value CORS_ALLOWED_ORIGINS "http://${public_host},http://${public_host}:8080,http://${public_host}:8081,http://localhost:8080,http://127.0.0.1:8080" set_value AI_SOULMATE_PUBLIC_URL "http://${public_host}:8080" set_value FRONTEND_URL "http://${public_host}:8080" -if ! grep -q '^TRIPO3D_API_KEY=' "$env_file"; then +if ! grep -q '^TRIPO3D_MODE=' "$env_file"; then + set_value TRIPO3D_MODE disabled +fi +tripo_mode="$(env_value TRIPO3D_MODE)" +if [[ "$tripo_mode" == "mock" ]]; then set_value TRIPO3D_API_KEY "" + set_value TRIPO3D_BASE_URL http://127.0.0.1:9/tripo-mock-blocked +else + if ! grep -q '^TRIPO3D_API_KEY=' "$env_file"; then + set_value TRIPO3D_API_KEY "" + fi + if ! grep -q '^TRIPO3D_BASE_URL=' "$env_file"; then + set_value TRIPO3D_BASE_URL https://api.tripo3d.com/v2/openapi + fi fi -set_value TRIPO3D_BASE_URL https://api.tripo3d.com/v2/openapi set_value TRIPO3D_DEFAULT_MODEL_VERSION v3.1-20260211 +if ! grep -q '^TRIPO3D_MOCK_QUEUE_DELAY_SECONDS=' "$env_file"; then + set_value TRIPO3D_MOCK_QUEUE_DELAY_SECONDS 2 +fi +if ! grep -q '^TRIPO3D_MOCK_RUN_DELAY_SECONDS=' "$env_file"; then + set_value TRIPO3D_MOCK_RUN_DELAY_SECONDS 8 +fi +if ! grep -q '^TRIPO3D_MOCK_H_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_H_CONCURRENCY 10 +fi +if ! grep -q '^TRIPO3D_MOCK_P_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_P_CONCURRENCY 5 +fi +if ! grep -q '^TRIPO3D_MOCK_IMAGE_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_IMAGE_CONCURRENCY 1 +fi +if ! grep -q '^TRIPO3D_MOCK_ANIMATION_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_ANIMATION_CONCURRENCY 10 +fi +if ! grep -q '^TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY 5 +fi +if ! grep -q '^TRIPO3D_MOCK_MESH_CONCURRENCY=' "$env_file"; then + set_value TRIPO3D_MOCK_MESH_CONCURRENCY 10 +fi +if ! grep -q '^TRIPO3D_MOCK_TASK_RETENTION_SECONDS=' "$env_file"; then + set_value TRIPO3D_MOCK_TASK_RETENTION_SECONDS 3600 +fi chmod 600 "$env_file" printf 'Backend environment configured without displaying secrets.\n' diff --git a/scripts/create-local-env.sh b/scripts/create-local-env.sh index 65cadac..768f256 100755 --- a/scripts/create-local-env.sh +++ b/scripts/create-local-env.sh @@ -103,6 +103,17 @@ FRONTEND_URL=http://127.0.0.1:8080 TRIPO3D_API_KEY= TRIPO3D_BASE_URL=https://api.tripo3d.com/v2/openapi TRIPO3D_DEFAULT_MODEL_VERSION=v3.1-20260211 +TRIPO3D_MODE=disabled +TRIPO3D_MOCK_PROFILE=not-selected +TRIPO3D_MOCK_QUEUE_DELAY_SECONDS=2 +TRIPO3D_MOCK_RUN_DELAY_SECONDS=8 +TRIPO3D_MOCK_H_CONCURRENCY=10 +TRIPO3D_MOCK_P_CONCURRENCY=5 +TRIPO3D_MOCK_IMAGE_CONCURRENCY=1 +TRIPO3D_MOCK_ANIMATION_CONCURRENCY=10 +TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY=5 +TRIPO3D_MOCK_MESH_CONCURRENCY=10 +TRIPO3D_MOCK_TASK_RETENTION_SECONDS=3600 EOF chmod 600 "$target_path" diff --git a/scripts/enable-tripo-mock.sh b/scripts/enable-tripo-mock.sh new file mode 100755 index 0000000..56c40f0 --- /dev/null +++ b/scripts/enable-tripo-mock.sh @@ -0,0 +1,81 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +profile="${2:-}" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +if [[ -z "$profile" ]]; then + echo "Choose a mock profile explicitly: rate-limits-page or model-pages-conservative" >&2 + exit 1 +fi + +case "$profile" in + rate-limits-page) + h_concurrency=10 + p_concurrency=5 + image_concurrency=1 + animation_concurrency=10 + postprocess_concurrency=5 + mesh_concurrency=10 + ;; + model-pages-conservative) + h_concurrency=3 + p_concurrency=3 + image_concurrency=1 + animation_concurrency=3 + postprocess_concurrency=5 + mesh_concurrency=10 + ;; + *) + echo "Unknown mock profile: $profile" >&2 + echo "Supported profiles: rate-limits-page, model-pages-conservative" >&2 + exit 1 + ;; +esac + +set_value() { + local key="$1" + local value="$2" + local temporary_file + + temporary_file="$(mktemp "${env_file}.tmp.XXXXXX")" + awk -v key="$key" -v value="$value" ' + BEGIN { prefix = key "="; found = 0 } + index($0, prefix) == 1 { + if (!found) print prefix value + found = 1 + next + } + { print } + END { if (!found) print prefix value } + ' "$env_file" > "$temporary_file" + chmod 600 "$temporary_file" + mv -f "$temporary_file" "$env_file" +} + +set_value TRIPO3D_MODE mock +set_value TRIPO3D_MOCK_PROFILE "$profile" +set_value TRIPO3D_API_KEY "" +set_value TRIPO3D_BASE_URL http://127.0.0.1:9/tripo-mock-blocked +set_value TRIPO3D_MOCK_H_CONCURRENCY "$h_concurrency" +set_value TRIPO3D_MOCK_P_CONCURRENCY "$p_concurrency" +set_value TRIPO3D_MOCK_IMAGE_CONCURRENCY "$image_concurrency" +set_value TRIPO3D_MOCK_ANIMATION_CONCURRENCY "$animation_concurrency" +set_value TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY "$postprocess_concurrency" +set_value TRIPO3D_MOCK_MESH_CONCURRENCY "$mesh_concurrency" +set_value TRIPO3D_MOCK_QUEUE_DELAY_SECONDS 2 +set_value TRIPO3D_MOCK_RUN_DELAY_SECONDS 8 +set_value TRIPO3D_MOCK_TASK_RETENTION_SECONDS 3600 + +chmod 600 "$env_file" + +echo "Tripo zero-cost mock profile enabled." +echo "Profile: $profile" +echo "H/P/Image/Animation/Postprocess/Mesh concurrency: ${h_concurrency}/${p_concurrency}/${image_concurrency}/${animation_concurrency}/${postprocess_concurrency}/${mesh_concurrency}" +echo "Real Tripo API key cleared and outbound base URL blocked." diff --git a/scripts/run-http-benchmark-suite.sh b/scripts/run-http-benchmark-suite.sh new file mode 100755 index 0000000..edb7e06 --- /dev/null +++ b/scripts/run-http-benchmark-suite.sh @@ -0,0 +1,77 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +run_id="${2:-$(date +%Y%m%d-%H%M%S)}" +request_count="${BENCHMARK_REQUESTS_PER_LEVEL:-200}" +output_root="${repo_root}/results/raw/${run_id}" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +read_value() { + local key="$1" + sed -n "s/^${key}=//p" "$env_file" | head -n 1 +} + +backend_bind_address="$(read_value BACKEND_BIND_ADDRESS)" +backend_host_port="$(read_value BACKEND_HOST_PORT)" +admin_backend_bind_address="$(read_value ADMIN_BACKEND_BIND_ADDRESS)" +admin_backend_host_port="$(read_value ADMIN_BACKEND_HOST_PORT)" + +if [[ -z "$backend_bind_address" || -z "$backend_host_port" || -z "$admin_backend_bind_address" || -z "$admin_backend_host_port" ]]; then + echo "Backend benchmark endpoints are missing from the environment file." >&2 + exit 1 +fi + +mkdir -p "$output_root" +sampler_stop="${output_root}/.resource-sampler-stop" +rm -f "$sampler_stop" +bash "${repo_root}/scripts/sample-benchmark-resources.sh" "$sampler_stop" \ + > "${output_root}/resources-during-load.csv" & +sampler_pid=$! + +stop_sampler() { + touch "$sampler_stop" + wait "$sampler_pid" 2>/dev/null || true + rm -f "$sampler_stop" +} +trap stop_sampler EXIT + +declare -a names=(user-health admin-health) +declare -a urls=( + "http://${backend_bind_address}:${backend_host_port}/api/health" + "http://${admin_backend_bind_address}:${admin_backend_host_port}/actuator/health" +) +declare -a concurrencies=(1 5 10 20 40) + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/snapshot-before.txt" + +for index in "${!names[@]}"; do + name="${names[$index]}" + url="${urls[$index]}" + for concurrency in "${concurrencies[@]}"; do + python3 "${repo_root}/benchmark/run-http-benchmark.py" \ + --url "$url" \ + --requests "$request_count" \ + --concurrency "$concurrency" \ + --warmup 5 \ + --timeout 10 \ + --expected-status 200 \ + --output "${output_root}/${name}-c${concurrency}.json" \ + > /dev/null + echo "Completed ${name} at concurrency ${concurrency}." + done +done + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/snapshot-after.txt" + +stop_sampler +trap - EXIT + +echo "HTTP benchmark suite completed: $output_root" diff --git a/scripts/run-tripo-mock-benchmark.sh b/scripts/run-tripo-mock-benchmark.sh new file mode 100755 index 0000000..aa0dedf --- /dev/null +++ b/scripts/run-tripo-mock-benchmark.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +run_id="${2:-$(date +%Y%m%d-%H%M%S)}" +output_root="${repo_root}/results/raw/${run_id}" +compose_file="${repo_root}/compose/docker-compose.backend.yml" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +read_value() { + local key="$1" + sed -n "s/^${key}=//p" "$env_file" | head -n 1 +} + +project_name="$(read_value BACKEND_COMPOSE_PROJECT_NAME)" +profile="$(read_value TRIPO3D_MOCK_PROFILE)" +if [[ -z "$project_name" ]]; then + echo "BACKEND_COMPOSE_PROJECT_NAME is missing." >&2 + exit 1 +fi + +compose_command=( + docker compose + --project-name "$project_name" + --env-file "$env_file" + -f "$compose_file" +) + +bash "${repo_root}/scripts/verify-tripo-mock.sh" "$env_file" +mkdir -p "$output_root" +sampler_stop="${output_root}/.resource-sampler-stop" +rm -f "$sampler_stop" +bash "${repo_root}/scripts/sample-benchmark-resources.sh" "$sampler_stop" \ + > "${output_root}/resources-during-tripo-mock.csv" & +sampler_pid=$! + +stop_sampler() { + touch "$sampler_stop" + wait "$sampler_pid" 2>/dev/null || true + rm -f "$sampler_stop" +} +trap stop_sampler EXIT + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/tripo-mock-snapshot-before.txt" + +container_id="$("${compose_command[@]}" ps -q backend)" +if [[ -z "$container_id" ]]; then + echo "Backend container is not running." >&2 + exit 1 +fi + +container_result="/tmp/tripo-mock-${run_id}.json" +"${compose_command[@]}" exec -T backend python \ + /app/tools/tripo_mock_benchmark.py \ + --output "$container_result" +docker cp "${container_id}:${container_result}" \ + "${output_root}/tripo-mock-${profile}.json" + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/tripo-mock-snapshot-after.txt" + +stop_sampler +trap - EXIT + +echo "Tripo mock benchmark completed: ${output_root}/tripo-mock-${profile}.json" diff --git a/scripts/run-user-e2e-smoke.sh b/scripts/run-user-e2e-smoke.sh new file mode 100755 index 0000000..f79e663 --- /dev/null +++ b/scripts/run-user-e2e-smoke.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +run_id="${2:-$(date +%Y%m%d-%H%M%S)}" +output_root="${repo_root}/results/raw/${run_id}" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +mkdir -p "$output_root" +bash "${repo_root}/scripts/verify-tripo-mock.sh" "$env_file" +sampler_stop="${output_root}/.resource-sampler-stop" +rm -f "$sampler_stop" +bash "${repo_root}/scripts/sample-benchmark-resources.sh" "$sampler_stop" \ + > "${output_root}/resources-during-user-e2e.csv" & +sampler_pid=$! + +stop_sampler() { + touch "$sampler_stop" + wait "$sampler_pid" 2>/dev/null || true + rm -f "$sampler_stop" +} +trap stop_sampler EXIT + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/user-e2e-snapshot-before.txt" + +set +e +python3 "${repo_root}/benchmark/run-user-e2e-smoke.py" \ + --base-url http://127.0.0.1:3001 \ + --output "${output_root}/user-e2e-smoke.json" +smoke_status=$? +set -e + +bash "${repo_root}/scripts/capture-benchmark-snapshot.sh" "$env_file" \ + > "${output_root}/user-e2e-snapshot-after.txt" + +stop_sampler +trap - EXIT + +if [[ "$smoke_status" -ne 0 ]]; then + echo "User E2E smoke failed; inspect: ${output_root}/user-e2e-smoke.json" >&2 + exit "$smoke_status" +fi + +echo "User E2E smoke completed: ${output_root}/user-e2e-smoke.json" diff --git a/scripts/sample-benchmark-resources.sh b/scripts/sample-benchmark-resources.sh new file mode 100755 index 0000000..2a5c28d --- /dev/null +++ b/scripts/sample-benchmark-resources.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +stop_file="${1:?stop file is required}" +interval_seconds="${2:-1}" + +if ! [[ "$interval_seconds" =~ ^[1-9][0-9]*$ ]]; then + echo "Sampling interval must be a positive integer." >&2 + exit 1 +fi + +printf '%s\n' 'captured_at,load_1m,mem_available_kib,container,cpu_percent,memory_usage,network_io,block_io,pids' +while [[ ! -e "$stop_file" ]]; do + captured_at="$(date --iso-8601=seconds)" + load_1m="$(awk '{print $1}' /proc/loadavg)" + mem_available_kib="$(awk '/^MemAvailable:/ {print $2}' /proc/meminfo)" + docker stats --no-stream \ + --format "${captured_at},${load_1m},${mem_available_kib},{{.Name}},{{.CPUPerc}},{{.MemUsage}},{{.NetIO}},{{.BlockIO}},{{.PIDs}}" \ + || true + sleep "$interval_seconds" +done diff --git a/scripts/verify-tripo-mock.sh b/scripts/verify-tripo-mock.sh new file mode 100755 index 0000000..ac1718c --- /dev/null +++ b/scripts/verify-tripo-mock.sh @@ -0,0 +1,127 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +env_file="${1:-${repo_root}/compose/.env}" +compose_file="${repo_root}/compose/docker-compose.backend.yml" + +if [[ ! -f "$env_file" ]]; then + echo "Environment file not found: $env_file" >&2 + exit 1 +fi + +read_value() { + local key="$1" + sed -n "s/^${key}=//p" "$env_file" | tail -n 1 +} + +mode="$(read_value TRIPO3D_MODE)" +api_key="$(read_value TRIPO3D_API_KEY)" +base_url="$(read_value TRIPO3D_BASE_URL)" +project_name="$(read_value BACKEND_COMPOSE_PROJECT_NAME)" +profile="$(read_value TRIPO3D_MOCK_PROFILE)" + +if [[ "$mode" != "mock" ]]; then + echo "TRIPO3D_MODE must be mock; found: ${mode:-unset}" >&2 + exit 1 +fi + +if [[ -n "$api_key" ]]; then + echo "TRIPO3D_API_KEY must be empty in a zero-cost benchmark." >&2 + exit 1 +fi + +if [[ "$base_url" != "http://127.0.0.1:9/tripo-mock-blocked" ]]; then + echo "TRIPO3D_BASE_URL is not the blocked loopback sentinel." >&2 + exit 1 +fi + +case "$profile" in + rate-limits-page) + expected_limits=(10 5 1 10 5 10) + ;; + model-pages-conservative) + expected_limits=(3 3 1 3 5 10) + ;; + *) + echo "TRIPO3D_MOCK_PROFILE was not explicitly selected." >&2 + exit 1 + ;; +esac + +limit_keys=( + TRIPO3D_MOCK_H_CONCURRENCY + TRIPO3D_MOCK_P_CONCURRENCY + TRIPO3D_MOCK_IMAGE_CONCURRENCY + TRIPO3D_MOCK_ANIMATION_CONCURRENCY + TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY + TRIPO3D_MOCK_MESH_CONCURRENCY +) +for index in "${!limit_keys[@]}"; do + actual_limit="$(read_value "${limit_keys[$index]}")" + if [[ "$actual_limit" != "${expected_limits[$index]}" ]]; then + echo "${limit_keys[$index]}=${actual_limit:-unset} does not match profile ${profile}." >&2 + exit 1 + fi +done + +if [[ "$(read_value TRIPO3D_MOCK_QUEUE_DELAY_SECONDS)" != "2" ]] \ + || [[ "$(read_value TRIPO3D_MOCK_RUN_DELAY_SECONDS)" != "8" ]]; then + echo "Mock queue/run delays do not match the benchmark baseline." >&2 + exit 1 +fi + +if [[ -z "$project_name" ]]; then + echo "BACKEND_COMPOSE_PROJECT_NAME is missing." >&2 + exit 1 +fi + +compose_command=( + docker compose + --project-name "$project_name" + --env-file "$env_file" + -f "$compose_file" +) + +"${compose_command[@]}" exec -T backend python -c ' +import os + +assert os.environ.get("TRIPO3D_MODE") == "mock" +assert not os.environ.get("TRIPO3D_API_KEY") +assert os.environ.get("TRIPO3D_BASE_URL") == "http://127.0.0.1:9/tripo-mock-blocked" +assert os.environ.get("TRIPO3D_MOCK_PROFILE") in {"rate-limits-page", "model-pages-conservative"} + +expected_profiles = { + "rate-limits-page": (10, 5, 1, 10, 5, 10), + "model-pages-conservative": (3, 3, 1, 3, 5, 10), +} +actual_limits = tuple(int(os.environ[name]) for name in ( + "TRIPO3D_MOCK_H_CONCURRENCY", + "TRIPO3D_MOCK_P_CONCURRENCY", + "TRIPO3D_MOCK_IMAGE_CONCURRENCY", + "TRIPO3D_MOCK_ANIMATION_CONCURRENCY", + "TRIPO3D_MOCK_POSTPROCESS_CONCURRENCY", + "TRIPO3D_MOCK_MESH_CONCURRENCY", +)) +assert actual_limits == expected_profiles[os.environ["TRIPO3D_MOCK_PROFILE"]] +assert float(os.environ["TRIPO3D_MOCK_QUEUE_DELAY_SECONDS"]) == 2 +assert float(os.environ["TRIPO3D_MOCK_RUN_DELAY_SECONDS"]) == 8 + +from services.tripo3d import Tripo3DService + +service = Tripo3DService() +assert service._api_url("task") == "mock://tripo-local/task" +assert service.billable_credits(40) == 0 +print("Container mock invariants passed.") +' + +backend_bind_address="$(read_value BACKEND_BIND_ADDRESS)" +backend_host_port="$(read_value BACKEND_HOST_PORT)" +health_json="$(curl --fail --silent --show-error --max-time 5 "http://${backend_bind_address}:${backend_host_port}/api/health")" +if ! printf '%s' "$health_json" | jq -e --arg profile "$profile" \ + '.status == "healthy" and .database == "connected" and .tripo_mode == "mock" and .tripo_mock_profile == $profile' >/dev/null; then + echo "Backend health response does not report tripo_mode=mock." >&2 + exit 1 +fi + +echo "Tripo zero-cost runtime verification passed."