85d495dd16
- add batch-scoped reconcile_runs persistence and queries - route batch detail and reconcile writes through batch_id/host_id - refresh production boards with host-scope acceptance artifacts - include latest real-host acceptance evidence for self_service and subscription
60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# Known Limitations & Production Gaps (V0.1)
|
|
|
|
This document covers known limitations that operators should be aware of before deploying `sub2api-cn-relay-manager` v0.1 to production.
|
|
|
|
## Core Limitations
|
|
|
|
### 1. No Automated Reconcile Scheduler (P2)
|
|
- Reconcilation must be triggered manually via `POST /api/providers/{providerID}/reconcile` or CLI.
|
|
- No cron/scheduler service is bundled.
|
|
- Workaround: set up a cron job on the host OS calling the HTTP API periodically.
|
|
|
|
### 2. Real sub2api Compatibility Is Verified on a Fresh Host, but Requires Explicit Operator Preparation
|
|
- Real-host validation has now been executed against a fresh redeployed sub2api host.
|
|
- Evidence: `artifacts/real-host-acceptance/20260518_redeploy_matrix`.
|
|
- Both `self_service` and `subscription` ordinary-user access paths reached `/v1/models -> 200`.
|
|
- However, host initialization alone is not enough: operators must explicitly create ordinary users, keep reusable credentials, bind keys to the correct group, and satisfy the billing/subscription prerequisites documented in `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`.
|
|
- This is therefore no longer a code-compatibility blocker; it is an explicit operational prerequisite.
|
|
|
|
### 3. Access Module Not Fully Structured per Implementation Plan
|
|
- The `access` package contains only `closure.go` (the combined close/validate logic).
|
|
- `planner.go`, `subscription_service.go`, `self_service_checker.go` are not separately extracted.
|
|
- All access logic is functional in `closure.go` but not split per the planned directory structure.
|
|
|
|
### 4. Reconcile Logic Inline in Provision Package
|
|
- Reconcile lives in `internal/provision/batch_detail_and_reconcile_service.go` rather than a separate `internal/reconcile/*` package.
|
|
- Functionally complete but structural gap vs implementation plan.
|
|
|
|
### 5. Standard Multi-stage Docker Build Still Depends on Outbound Module Download
|
|
- `Dockerfile.local` has been validated as the recommended proxy-safe build path.
|
|
- `scripts/build_local_image.sh` now prebuilds the Linux binary on the host and produces `sub2api-cn-relay-manager:local` reliably in this environment.
|
|
- The standard multi-stage `Dockerfile` still requires outbound Go module download from inside the container build context; in restricted networks, prefer the local-image path.
|
|
|
|
## Accepted Design Trade-offs
|
|
|
|
### 6. CLI Run Functions Not Unit-Tested
|
|
- `runInstallPack`, `runImportProvider`, `runPreviewProvider`, `runRollbackProvider`, `runReconcileProvider`, `findProvider` connect to real SQLite/sub2api — these are 0% covered in unit tests.
|
|
- The `execute()` dispatch and all `parse*` functions are fully tested.
|
|
- In an integration/E2E context these functions are exercised through the host stub.
|
|
|
|
### 7. No Web UI
|
|
- Administration is through CLI and HTTP API only.
|
|
- Consistent with MVP scope defined in PRD.
|
|
|
|
## Operational Notes
|
|
|
|
### Token Security
|
|
- `SUB2API_CRM_ADMIN_TOKEN` must be at least 20 characters, rotated outside source control.
|
|
- API keys imported via `--access-api-key` are used for gateway probe calls — they are not stored in control-plane state (only key fingerprint/hash is stored).
|
|
|
|
### Database
|
|
- SQLite is the only supported database backend for v0.1.
|
|
- SQLite WAL mode is handled automatically by the driver.
|
|
- For high availability, mount the SQLite file on persistent storage (host volume or NFS).
|
|
- No external DB migration tool is needed — Flyway-style migrations are embedded in the binary.
|
|
|
|
### Monitoring
|
|
- Only `/healthz` endpoint is available for container orchestration liveness checks.
|
|
- No metrics, structured logging, or APM integration in v0.1.
|
|
- Use standard log collection (stdout/json) for observability.
|