sub2api-cn-relay-manager/docs/KNOWN_LIMITATIONS.md

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.