115 lines
4.7 KiB
Markdown
115 lines
4.7 KiB
Markdown
# Go modular backend
|
|
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
docker build -f backend/Dockerfile.alpine \
|
|
-t REGISTRY/PROJECT/zhinian-go-api:TAG backend/
|
|
```
|
|
|
|
Standard multi-stage build (needs the `golang` builder image):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](../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.
|