This directory contains the production application backend. Go is the sole runtime owner of /api, /uploads, and /generated-results, including browser sessions, authorization, persistence, provider calls, and the embedded WorkerLoop. The frontend is a static Next.js export served by Nginx and calls these Go routes through the public same-origin Ingress.

Implemented Modules:

identity and administration: legacy zhinian_session HMAC/chunking, database-refreshed authorization, password lifecycle, accounts, and organizations.
assets: scoped registration, upload, download, deletion, local filesystem, bounded remote import, and Alibaba Cloud OSS adapters.
jobs, providers, and orchestration: provider preparation/protocols, idempotent creation, embedded WorkerLoop, retries, output assets, usage, refunds, Seedance/MiniMax H3 settlement, and signed Webhooks.
billing and usage: integer-fen quote/wallet/ledger/catalog behavior and tenant-scoped reports.
templates, prompt, settings, and logging: the remaining compatibility modules used by the HTTP surface.
postgres: fail-closed configuration, code-enforced plaintext sslmode=disable, readiness, atomic account mutations, and calls to the existing claim and wallet PostgreSQL functions. PostgreSQL is the production relational source of truth.
localstore: a mutex-protected, non-durable, single-process development store covering the same business Module ports.
httpapi: the complete checked-in route compatibility surface.
application: composition and the cmd/zhinian-api process entry point.

From the repository root:

npm run go:fmt
npm run go:test
npm run go:vet
npm run go:build

Container images

Self-contained build (recommended for China CI; single command, only the alpine base image is pulled — the Go toolchain comes from Alpine's packages via the Aliyun apk mirror and modules come from goproxy.cn):

docker build -f backend/Dockerfile.alpine \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/

Standard multi-stage build (needs the golang builder image):

docker build -f backend/Dockerfile -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/

Mirror-friendly build (override the base images when the registry accelerator cannot serve docker.io images):

docker build -f backend/Dockerfile \
  --build-arg GOLANG_IMAGE=<mirror>/golang:1.21-alpine \
  --build-arg RUNTIME_IMAGE=<mirror>/alpine:3.20 \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/

Prebuilt-binary build (no golang image at all; compile the static binary on any Go 1.21 machine, then assemble from alpine only):

cd backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w" -o zhinian-api.linux ./cmd/zhinian-api
docker build -f backend/Dockerfile.runtime \
  -t REGISTRY/PROJECT/zhinian-go-api:TAG backend/

The runner defaults to CGO_ENABLED=0 for reproducible cross-platform builds. To exercise the backend locally, listen on port 8080 and route browser API requests there with a same-origin development proxy:

ZHINIAN_DATA_BACKEND=local GO_BACKEND_PORT=8080 ./backend/zhinian-api

In local mode, persistent business data is process-local and is discarded on restart; it is intended only for development and contract smoke tests. The default demo identity supports the optional-auth frontend development flow.

First super administrator

On the first PostgreSQL deployment, the first super administrator is created from configuration at startup — no separate script or CLI step is needed. When the three variables below are all present and the process runs against PostgreSQL, startup creates the account exactly once and skips the bootstrap when any super administrator (including a disabled one) already exists:

ZHINIAN_BOOTSTRAP_ADMIN_PHONE
ZHINIAN_BOOTSTRAP_ADMIN_PASSWORD (minimum 8 characters)
ZHINIAN_BOOTSTRAP_ADMIN_NAME (defaults to 平台超级管理员)

A failed bootstrap (invalid phone, short password, database error) fails process startup so a misconfigured bootstrap is visible instead of silently missing. Local development mode keeps the seeded demo administrator and never bootstrap-creates accounts.

Production routing, Secret ownership, probes, and rollout commands are defined in ../docs/DEPLOYMENT.md and ../deploy/ack/. Go owns the session signing Secret and backend runtime configuration; the static Web workload receives neither. PostgreSQL does not use TLS, so production must use the RDS internal endpoint and restrict access with VPC boundaries, security groups, and allowlists. Validate RDS connectivity, OSS, providers, Webhooks, embedded Worker recovery, and rollback behavior for each production release.