feat: establish Quant OS production-80 architecture

2026-07-30 22:59:25 +08:00
parent 919c64c679
commit 26cc814f3f
67 changed files with 7005 additions and 142 deletions
@@ -0,0 +1,59 @@
+# Quant OS public status operations
+
+The repository is the source of truth for the public status page. A deployment
+contains exactly:
+
+```text
+/srv/www/quant-os/
+  releases/<git-sha>/
+    index.html
+    status-data.js
+  status -> releases/<git-sha>
+```
+
+Deployment invariants:
+
+1. run `python3 tools/build_public_status.py --check` and the full local suite;
+2. deploy from a clean, pushed commit and name the release with that full SHA;
+3. acquire the web-root deployment lock and copy into a same-filesystem
+   `.incoming-<sha>` directory;
+4. require exactly two regular, non-symlink payload files and compare local and
+   staged SHA-256 for both;
+5. atomically rename the verified incoming directory to the immutable release;
+6. create a temporary relative symlink and activate it with one atomic rename;
+7. install [`nginx/quant-os-static.conf`](nginx/quant-os-static.conf), run
+   `nginx -t`, then reload;
+8. verify the canonical page, generated JavaScript, cache header and all legacy
+   redirects from a public client;
+9. keep the previous release for rollback.
+
+The server-side deploy and activation are executable and fail closed:
+
+```bash
+ops/deploy_static_status.sh <full-git-sha> <staged-status-dir>
+ops/activate_static_status.sh <previous-full-git-sha>
+```
+
+The first command rejects a symlinked source root, symlink payloads,
+directories and any third source entry,
+holds `.status-deploy.lock` across staging and activation, verifies both
+SHA-256 values, atomically promotes `.incoming-<sha>`, and refuses to overwrite
+an existing release. Promoted payload files and their release directory are
+owner read-only. The second command is the rollback/activation primitive;
+when called directly it takes the same lock and switches only a relative
+symlink. A stale lock or incoming directory means a prior process may have
+crashed: inspect it and confirm no deploy is running before removing it.
+
+Nginx is deliberately two-stage:
+
+1. include `nginx/quant-os-static.conf` in the existing HTTPS server block,
+   run `nginx -t`, reload, and verify `/quant-os/status/`;
+2. only then include `nginx/quant-os-legacy-redirects-302.conf`, preserving the
+   existing broad `/quants-strategies/` route for other projects;
+3. after an observation period and a separate production change, replace the
+   302 include with `quant-os-legacy-redirects-308.conf`.
+
+Rollback only changes the `status` symlink to the previously verified release
+and reloads no application state. The page is a static, redacted build-time
+snapshot; it must never contain credentials, local paths, market data, account
+identifiers, positions or fills.