docs: integrate plaintext PostgreSQL decision
This commit is contained in:
brother7 committed
1 parent
ed978142eb
commit
acd929c704
10 files changed
+146
-40
No files matched your search
@@ -15,7 +15,8 @@ and are not a supported production path.
|
||||
|
||||
## Approved Target Flows
|
||||
|
||||
The implementation and desired ACK routing are present in `b14b4fc`.
|
||||
The static implementation and desired ACK routing are present in `b14b4fc`;
|
||||
`ed97814` adds the plaintext PostgreSQL transport correction.
|
||||
Production is already online, but the static revision and exact live Service
|
||||
ownership have not been confirmed from cluster configuration or logs:
|
||||
|
||||
@@ -24,7 +25,7 @@ ownership have not been confirmed from cluster configuration or logs:
|
||||
| Browser UI | Browser | Same-origin Ingress -> Nginx static Web | Preserve current page URLs; Nginx performs no application logic. |
|
||||
| Browser identity | Browser auth Module | Same-origin Ingress -> Go `GET /api/auth/me` | Browser automatically sends HttpOnly Cookie; validate anonymous/authenticated response shapes, keep no token in JavaScript, and use client guards only for UX. |
|
||||
| Browser business/file requests | Browser components | Same-origin Ingress -> Go `/api`, `/uploads`, `/generated-results` | Go revalidates session/account/organization/sessionVersion and enforces every protected action. |
|
||||
| Backend persistence | Go Modules | PostgreSQL Adapter -> RDS | Parameterized queries and transactions; fail closed in production. |
|
||||
| Backend persistence | Go Modules | PostgreSQL Adapter -> internal RDS endpoint | Parameterized queries and transactions; fail closed in production; code-enforced plaintext (`sslmode=disable`) within VPC/security-group/allowlist isolation. |
|
||||
| Task execution | Embedded Go WorkerLoop | RDS claim -> provider -> OSS -> RDS -> Webhook | Bounded concurrency, recoverable leases, one owner for external side effects. |
|
||||
| Asset lifecycle | Go Assets | OSS plus RDS metadata | Shared storage required before horizontal scaling. |
|
||||
| Schema rollout | Manual operator or dedicated CI | RDS | Execute immutable versioned SQL plus grants outside long-lived workloads; no Web-image migration Job. |
|
||||
@@ -39,7 +40,9 @@ ownership have not been confirmed from cluster configuration or logs:
|
||||
|
||||
## External Interfaces
|
||||
|
||||
- Alibaba Cloud RDS PostgreSQL via its internal endpoint and verified TLS CA.
|
||||
- Alibaba Cloud RDS PostgreSQL via its internal endpoint using code-enforced
|
||||
plaintext; VPC, security-group, and RDS allowlist controls are the transport
|
||||
isolation boundary.
|
||||
- Alibaba Cloud ACK resources under `deploy/ack/`.
|
||||
- Live production at `https://nianxxaigc.nianxx.cn`; public `/api/ready` has returned HTTP 200 with PostgreSQL configured, without proving the owning Service.
|
||||
- The legacy internal Worker prefix is denied by Ingress; production uses the
|
||||
@@ -47,7 +50,8 @@ ownership have not been confirmed from cluster configuration or logs:
|
||||
|
||||
The accepted production topology uses the embedded Go WorkerLoop. The current
|
||||
live revision produces an RSC error for authenticated `/create`; the rollout
|
||||
must deploy `b14b4fc` under immutable image references and smoke login,
|
||||
must deploy `ed97814` under immutable image references and smoke PostgreSQL
|
||||
bootstrap/readiness, login,
|
||||
authenticated routes, logout, roles, `/healthz`, `/api/health`, and
|
||||
`/api/ready`.
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
| `database/migrations/` | Immutable versioned PostgreSQL schema changes | Executed manually/through dedicated operator CI; no migration Job reuses Web. |
|
||||
| `deploy/ack/` | Seven ACK manifests plus Secret template | Static Web + Go topology; Web has no runtime config/Secret and Go owns the session Secret. |
|
||||
| `backend/cmd/zhinian-api` | Go application entrypoint, configuration, HTTP server composition, health/readiness | Sole runtime API owner targeted by checked-in Ingress. |
|
||||
| `backend/internal/*` | ADR-003 deep modules and adapters, 18 packages: `identity`, `administration`, `assets`, `billing`, `usage`, `jobs`, `providers`, `webhook`, `httpapi`, `publicapi`, `application`, `orchestration`, `postgres`, `localstore`, `logging`, `settings`, `templates`, `prompt` | Implemented in `b14b4fc`; publication of immutable images and rollout of the static Web + Go revision remain pending. |
|
||||
| `backend/internal/*` | ADR-003 deep modules and adapters, 18 packages: `identity`, `administration`, `assets`, `billing`, `usage`, `jobs`, `providers`, `webhook`, `httpapi`, `publicapi`, `application`, `orchestration`, `postgres`, `localstore`, `logging`, `settings`, `templates`, `prompt` | Implemented in `b14b4fc`; `ed97814` enforces plaintext PostgreSQL. Publication of immutable images and live rollout remain pending. |
|
||||
| `contracts/**/*.json` | Language-neutral HTTP/Cookie/auth/jobs/billing/storage/webhook contract fixtures | Shared acceptance source for TypeScript and Go consumers. |
|
||||
|
||||
## Dependency Direction
|
||||
@@ -46,7 +46,8 @@ Real internal seams are PostgreSQL transport, object storage, generation provide
|
||||
|
||||
- `database/migrations/` and the two concurrency-sensitive PostgreSQL functions.
|
||||
- Account authentication/password transactions and billing wallet idempotency.
|
||||
- ACK Secrets, RDS CA mounting, Ingress protection for internal Worker routes, and pool connection budgeting.
|
||||
- ACK Secrets, private-network enforcement for unencrypted RDS traffic,
|
||||
Ingress protection for internal Worker routes, and pool connection budgeting.
|
||||
- `backend/internal/{postgres,jobs,billing}`: claim and wallet correctness across Go replica scaling until WorkerLoop concurrency is deliberate.
|
||||
- Static Web image construction/container startup still needs CI smoke evidence.
|
||||
- Go `emptyDir` file state is lost on Pod replacement when OSS is absent.
|
||||
|
||||
@@ -2,14 +2,19 @@
|
||||
|
||||
## Current Architecture
|
||||
|
||||
The first production deployment is online at `https://nianxxaigc.nianxx.cn`. The public `/api/ready` endpoint has been observed returning HTTP 200 with PostgreSQL configured. The exact live Service owner for each path has not been confirmed through cluster configuration or logs, so the deployed routing shape is not inferred here.
|
||||
The first production deployment is online at `https://nianxxaigc.nianxx.cn`.
|
||||
An earlier public `/api/ready` response returned HTTP 200 with PostgreSQL
|
||||
configured, but the latest observed Go API startup fails during bootstrap
|
||||
because the RDS endpoint refuses TLS. The exact live Service owner and deployed
|
||||
image revision for each path have not been confirmed through cluster
|
||||
configuration or logs.
|
||||
|
||||
The live revision predates `b14b4fc` and authenticated `/create` currently
|
||||
triggers a production RSC error. The repository now implements the stricter
|
||||
ADR-003 boundary: Next.js statically exports pages, unprivileged Nginx serves
|
||||
them, the browser reads identity from Go `/api/auth/me`, and Go owns every
|
||||
runtime API/file route plus database-backed authorization and the embedded
|
||||
WorkerLoop. The new images and ACK configuration have not yet been deployed.
|
||||
The repository implements the strict ADR-003 boundary: Next.js statically
|
||||
exports pages, unprivileged Nginx serves them, the browser reads identity from
|
||||
Go `/api/auth/me`, and Go owns every runtime API/file route plus database-backed
|
||||
authorization and the embedded WorkerLoop. Revision `ed97814` additionally
|
||||
forces PostgreSQL plaintext for the TLS-refusing RDS endpoint. Deployment and
|
||||
live validation of that exact revision remain pending.
|
||||
|
||||
## Approved Target Architecture
|
||||
|
||||
@@ -17,9 +22,9 @@ The accepted target in ADR-003 is a same-origin static Next.js export on Nginx p
|
||||
|
||||
| Target component | Responsibility | Constraint | Implementation state |
|
||||
|---|---|---|---|
|
||||
| Static Web | Next.js build output (`out/`) and browser UI served by Nginx | No SSR, Middleware, Route Handlers, runtime configuration, application Secret, or internal Go URL. | Implemented and statically verified in `b14b4fc`; deployment pending. |
|
||||
| Static Web | Next.js build output (`out/`) and browser UI served by Nginx | No SSR, Middleware, Route Handlers, runtime configuration, application Secret, or internal Go URL. | Implemented and statically verified in `b14b4fc`; publish the image from `ed97814` with the matching Go release. |
|
||||
| Go backend | Existing HTTP/file contracts, identity, administration, assets, jobs, billing, usage, providers, storage, Webhooks, readiness | Owns relational access and embeds the WorkerLoop in the approved topology. | Implemented in `backend/`; production is online, but exact live path ownership is not asserted without cluster evidence. |
|
||||
| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. | Repository procedure requires manual SQL (migrations 0001/0002) plus role grants; live execution evidence remains to be confirmed. |
|
||||
| RDS PostgreSQL | Relational state and cross-instance concurrency | Retains versioned migrations and both concurrency-sensitive database functions. Clients enforce plaintext (`sslmode=disable`); use only the internal endpoint protected by VPC, security groups, and an RDS allowlist. | Repository procedure requires manual SQL (migrations 0001/0002) plus role grants; live plaintext bootstrap/readiness and network-isolation evidence remain to be confirmed. |
|
||||
| Schema operator/CI | Schema and application-role grants | Runs versioned SQL outside long-lived workloads; never reuses the static Web image. | First-deployment procedure is manual; no migration Job manifest is shipped. |
|
||||
| Alibaba Cloud OSS | Shared generated/uploaded assets | Must be production-ready before horizontal workload scaling. | Still behind a storage Adapter; not validated against real OSS. |
|
||||
|
||||
@@ -42,6 +47,9 @@ replica until file storage is shared.
|
||||
## Important Boundaries
|
||||
|
||||
- Production backend selection is explicit and fail-closed; never turn a PostgreSQL configuration failure into local JSON fallback.
|
||||
- PostgreSQL transport is code-enforced plaintext because the selected RDS
|
||||
endpoint refuses TLS. Database traffic must stay on the Alibaba Cloud private
|
||||
network and be restricted with VPC, security-group, and allowlist controls.
|
||||
- Store callers depend on stable store interfaces, not `pg` or SQL details.
|
||||
- Multi-statement consistency uses one transaction client; atomic job claim and wallet posting remain database functions.
|
||||
- Database credentials and the session-signing Secret belong to Go and the
|
||||
@@ -56,8 +64,9 @@ replica until file storage is shared.
|
||||
## Related Decisions
|
||||
|
||||
- Current implementation: `RDS-001` and `RDS-002` (schema execution now manual SQL per `DEP-001`).
|
||||
- Accepted implementation: `ADR-003` as amended by `b14b4fc`; production is
|
||||
online, but the new static revision and exact live routing remain unverified.
|
||||
- Accepted implementation: `ADR-003` as amended by `b14b4fc`, plus the
|
||||
`RDS-001` transport amendment implemented in `ed97814`; production is online,
|
||||
but the exact revision and live routing remain unverified.
|
||||
- First-deployment model: `DEP-001`.
|
||||
|
||||
## Last Updated
|
||||
|
||||
Reference in new issue
Block a user