AnixOps Control

anix-control is the control-plane service for AnixOps. It combines a Go backend, Vue 3 admin/user frontend, node communication APIs, subscription generation, payment/order management, traffic statistics, and the in-progress minimal forwarding module.

The project is being hardened toward a stable, testable, GitHub Actions-only release process. Treat docs/features.md as the source of truth for implemented, partial, planned, compatibility, and deferred features.

• Main branch: go_dev.
• Backend: Go module github.com/AnixOps/anix-control/v4; the toolchain is pinned to Go 1.26.8 in CI.
• Frontend: Vue 3 + Vite under web/, Node.js 22 in CI.
• Default database: SQLite, with PostgreSQL migration/dry-run tooling.
• Current release: v4.2.0-rc.2 (the formal plugin-only Control release). It ships a signed sixteen-package cohort, package-host lifecycle controls, immutable V4 evidence, and compatibility-gated Agent integration.
• Product delivery line: v4.0.0-alpha.* remains immutable historical preview evidence. It is not an alternative trust root or release channel for the formal V4 package cohort.
• Agent-first status: the anix.agent.v1 bidirectional gRPC control stream delivers signed package lifecycle work. Legacy data-plane protocols remain available for controlled compatibility and rollback.

Do not infer production completeness from a route or UI existing. Check docs/features.md, TODO.md, and docs/audit/test-gap.md before marking a feature complete.

V4 keeps REST/UniProxy, the legacy panel-node gRPC services, and existing WebSocket paths available as compatibility surfaces. A fresh plugin-only deployment must bootstrap the signed identity-platform package from the verified release evidence before enabling Control package execution; the release container image ships that package and imports it on first start, and the V4 release installer performs the same verified bootstrap. Operators should retain the documented rollback plan throughout rollout. Package hosts may invoke narrowly scoped, kernel-owned compatibility bridge operations to preserve established route semantics; there is no direct HTTP fallback when a signed package is unavailable.

• Documentation landing page: docs/README.md
• Feature status register: docs/features.md
• Roadmap: ROADMAP.md
• Concrete backlog: TODO.md
• Changelog: CHANGELOG.md
• Brand and artifact migration: docs/BRAND_MIGRATION.md
• Deployment guide (containers first): docs/DEPLOYMENT.md
• Container design and multi-replica status: docs/architecture/container-deployment.md
• Upgrade runbook: docs/UPGRADE.md
• Native systemd install (frozen): docs/guide/release-installation.md
• Legacy migration plan: docs/guide/legacy-migration.md
• Manual intervention requirements: docs/manual-intervention.md
• Audit registers: docs/audit/repository-audit.md, docs/audit/security-risk.md, docs/audit/concurrency-risk.md, docs/audit/performance-risk.md, docs/audit/test-gap.md

See docs/reference/repository-layout.md (contributor and agent rules: AGENTS.md).

Generated local outputs should stay ignored and out of the source tree. Use:

bash config/deploy/clean_local_build_artifacts.sh --dry-run
bash config/deploy/clean_local_build_artifacts.sh --dry-run --include-deploy-backups

Containers are the primary deployment. Each release publishes a signed, multi-architecture image ghcr.io/anixops/anix-control (digest in the release docker-image.txt) that needs no config file: run it with docker-compose.prod.yml and an external PostgreSQL, or with the Helm chart in config/deploy/helm/anix-control. Steps: docs/DEPLOYMENT.md.

The native systemd installer is frozen (it keeps working, without new features). It downloads checked GitHub Release assets and does not clone the repository or build on the target host. Pin the production tag:

export VERSION=v4.0.0
curl -fsSL \
  "https://raw.githubusercontent.com/AnixOps/anix-control/${VERSION}/scripts/install.sh" \
  -o /tmp/anix-control-install.sh
sudo bash /tmp/anix-control-install.sh install --version "${VERSION}" --admin-email "admin@example.com"
rm -f /tmp/anix-control-install.sh

See the release installation guide for the systemd path's reverse proxy, update, rollback, and security steps. Existing panel or foreign panel migrations must follow the legacy migration plan.

The --include-deploy-backups mode is only for ignored local deploy archive leftovers in the checkout, such as stale frontend tarballs and internal zip archives. It keeps database backups, config, certificates, and web/node_modules.

Prefer the same checks GitHub Actions runs. Focused local checks are fine while developing; release builds are not.

Start an isolated local development instance with:

make run

On first use this creates the ignored config/config.dev.yaml from config/config.dev.yaml.example. It listens on 127.0.0.1:19080 for the API, 127.0.0.1:19000 for the frontend, and 127.0.0.1:50052 for gRPC, and uses a separate development SQLite database. An already running system anix-control service and its production-style ports are not changed. Set RUN_CONFIG=/path/to/config.yaml to run with another explicit configuration.

go test ./...
go test -race ./...
bash api/grpc/gen.sh
git diff --exit-code -- api/grpc/v2boardpb
bash config/deploy/clean_local_build_artifacts.sh --dry-run

Frontend checks are run in CI from a clean checkout:

cd web
npm ci
npm audit --audit-level=moderate
npm test
npm run build

After local frontend verification, remove generated outputs with:

bash config/deploy/clean_local_build_artifacts.sh
bash config/deploy/clean_local_build_artifacts.sh --include-deploy-backups

All release artifacts must be built by GitHub Actions. Do not build release binaries, frontend archives, Docker metadata, checksums, SBOMs, or release manifests on a production host.

Release jobs accept stable, alpha, beta, and release-candidate tags such as v4.0.0, v4.0.0-alpha.7, v4.0.0-beta.1, and v4.0.0-rc.1. Tag builds produce:

• multi-platform anix-control-* backend artifacts
• anix-control-frontend.* archives
• checksum file
• SPDX SBOM
• migration dry-run evidence
• Docker metadata
• machine-readable RELEASE_MANIFEST.json
• operator deployment runbook
• deterministic RELEASE_NOTES.md plus generated GitHub release notes

Local deploy scripts that perform source-tree builds are guarded and are not a release path. See docs/DEPLOYMENT.md and docs/UPGRADE.md for operator deployment, upgrade, and rollback expectations.

• Keep secrets, production databases, TLS private keys, payment credentials, and domain/server changes out of commits.
• Payment callbacks are provider-specific compatibility surfaces; do not normalize or enable them without provider verification tests.
• Alipay, WeChat, and USDT payment callbacks remain planned and are blocked from enable/use until implementation and tests exist.
• Forwarding features must remain auditable, role-scoped, and covered by quota, permission, runtime, and cancellation tests.

Some routes intentionally keep legacy or external protocol behavior:

• /api/v1/client/subscribe?token=
• /{subscribe_path}/:token
• /api/v1/server/UniProxy/*
• /api/v2/server/UniProxy/*
• /api/v2/node/register
• /api/v2/node/heartbeat
• Telegram webhooks
• payment callbacks/webhooks
• forwarding agent and internal traffic upload endpoints

The v2_* database tables, v2board protobuf wire namespace, and historical SQLite path are intentionally retained during the migration. The Go module has moved to github.com/AnixOps/anix-control/v4.

Do not change these response shapes without checking docs/features.md and adding compatibility tests.