118 lines
7.5 KiB
Markdown
118 lines
7.5 KiB
Markdown
---
|
||
title: Metrix Offline Deployment & Sub‑module Migration Guide
|
||
type: curated
|
||
permalink: main/projects/d5a7f581-c442-4554-87b9-ee723b8b0258/curated/development/metrix-offline-deployment-sub-module-migration-guide
|
||
stable_id: bb1539bd-c7f2-4d57-9257-8e4b2b4672cb
|
||
scope: project
|
||
project_id: d5a7f581-c442-4554-87b9-ee723b8b0258
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: deployment
|
||
revision: 1
|
||
source_memory_ids: []
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: e660bc7bb4fc5ccda47decb4d514874a148ed9b2
|
||
source_git_commits:
|
||
- e660bc7bb4fc5ccda47decb4d514874a148ed9b2
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: git-restore
|
||
source_count: 29
|
||
source_revisions:
|
||
memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e: '1'
|
||
memory:a3896ad9-d30c-4963-9232-a7d1ab571d19: '2'
|
||
memory:bc21af00-1127-44f8-93b7-aa484a7041c2: '1'
|
||
memory:5924806e-b234-49f7-b971-3c844fd07cf3: '3'
|
||
source_dispositions:
|
||
processed: 29
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- memory:6c4cbc6d-a59b-4128-9d6a-cb9652cff00e
|
||
- memory:a3896ad9-d30c-4963-9232-a7d1ab571d19
|
||
- memory:bc21af00-1127-44f8-93b7-aa484a7041c2
|
||
- memory:5924806e-b234-49f7-b971-3c844fd07cf3
|
||
job_cited_source_ids: []
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences: []
|
||
source_cursor: 162
|
||
source_hash: e2fcea7c8a9e0df7a91925fb2a9beabd922058868310effc908f95df2d78b218
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: null
|
||
created_at: '2026-08-19T02:32:32.719008+00:00'
|
||
updated_at: '2026-09-23T15:09:24.136251+00:00'
|
||
tags:
|
||
- deployment
|
||
- docker
|
||
- fastapi
|
||
- vue
|
||
- ci
|
||
- offline
|
||
- security
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
## Overview
|
||
|
||
The **Metrix** platform is a modular FastAPI + Vue 3 system deployed via Docker. The architecture consists of an API gateway, core modules (containers, database, scripts, storage, internal PyPI), and a SPA front‑end built with Vite and Naïve‑UI. All modules are auto‑registered through `APP_MODULE` and use an action‑based RBAC model.
|
||
|
||
| Layer | Component | Key notes |
|
||
|------|-----------|-----------|
|
||
| API Gateway / FastAPI Core | `git:server/app/main.py` | FastAPI factory, OpenAPI, CORS, SPA fallback |
|
||
| Module Registry | `git:server/app/modules/registry.py` | Discovers `APP_MODULE` objects, validates keys & deps |
|
||
| Permission Framework | `git:server/app/core/permissions.py` | Action‑based RBAC; `action:* → read` |
|
||
| Security Utils | `git:server/app/core/security.py` | PBKDF2‑SHA256 hashing, `mtx_` API‑tokens, Fernet secrets |
|
||
| Database Sub‑system | ORM models, `git:server/app/db/init.py`, migrations | SQLAlchemy sessions, alembic‑style registry |
|
||
| Containers Module | Docker client, WS xterm.js terminal | `modules/containers/...` |
|
||
| Storage API | FTP/SFTP adapters, file‑tree service (depth/size caps) |
|
||
| Offline Docker Deployment | `scripts/build_docker.py` → `metrix‑app‑latest.tar` (+ optional MySQL & internal PyPI) |
|
||
| Front‑End SPA | Vue 3 + TypeScript + Vite + Naïve‑UI; i18n (EN/ZH), dark/light themes, Monaco + Shiki, Playwright tests |
|
||
| CI / Regression | Playwright end‑to‑end suite (`tests/regression/framework.spec.ts`) |
|
||
|
||
## Current Deployment State (as of 2026‑08‑26)
|
||
|
||
- **Backend**: FastAPI fully running; all core modules (`containers`, `database`, `scripts`, `storage`, internal PyPI) registered via `APP_MODULE`. Action‑based RBAC active; Vaultwarden is the source of credentials (`global_guidance_memory:105b328f‑…`).
|
||
- **Frontend**: Vue 3 SPA stable, English/Chinese toggle, dark/light theme sync (Shiki pending). The new **DatabasePanel** supports keyword search (`POST /api/database/table/query`) with pagination and filter persistence.
|
||
- **Instances**: A second instance `capacityrepost‑web:113ff5c` is live; health‑check (`/health`) returns **200** and the image SHA‑256 matches the offline bundle.
|
||
- **Validation**: Example `sector` table queries return expected row counts; UI renders correctly at both 1440 px and 720 px widths.
|
||
- **Conclusion**: The system is **stable**; only high‑priority open items remain (Shiki theme sync, fine‑grained API‑token permissions).
|
||
|
||
## Deployment Artifacts
|
||
|
||
- **Docker images** are built with `scripts/build_docker.py`, producing `metrix‑app‑latest.tar`. The tar contains the FastAPI image, the Vue SPA static assets, and an optional MySQL image for air‑gapped environments.
|
||
- **Compose files** define the primary service (`metrix‑app`) and the secondary `capacityrepost‑web` with its own MySQL container.
|
||
- **Internal PyPI server** (`pypiserver` container) provides offline wheels; the UI is exposed at `/pypi`.
|
||
- **Offline bundle** supports deployments without Internet access.
|
||
|
||
## Key Deployment Decisions
|
||
|
||
| Decision ID | Summary | Rationale | Status |
|
||
|------------|----------|-----------|--------|
|
||
| `e71d9113‑be70‑4792‑8a7d‑81df157ea9a0` | Keep **CapacityReport** as independent sub‑module + Docker image | Isolated UI & historic data handling | Implemented |
|
||
| `52d53ae2‑ce5b‑4207‑9813‑0c9d3de029ce` | Switch editor highlighting to **Shiki** | Monaco mis‑highlights multiline f‑strings | Integrated (theme sync pending) |
|
||
| `761650df‑f1df‑4e5a‑b23a‑adf2d01d5c9f` | Adopt **action‑based permission model** | Simplify checks, avoid page rule duplication | All modules migrated |
|
||
| `34271d12‑a706‑491b‑a06b‑f561e81f7346` | Consolidate script‑run retention to `{max_count, max_days}` | Remove overlapping policies | Unified |
|
||
| `cf3e85fe‑dcf3‑4af3‑9a17‑edfe63b2f56c` | Freeze local `docs/project_context.md`; **MemRelay only** stores memory | Avoid bidirectional sync, per user request | File read‑only, MemRelay source of truth |
|
||
| `5924806e‑b234‑49f7‑b971‑3c844fd07cf3` | Formalise **workflow**: Chinese‑first, KISS/YAGNI, ordered steps (implement→clean→memory→docs→commit) | Standardise practice | Documented, tooling enforced |
|
||
| *Docker‑socket mount* | Mount host Docker socket into `metrix‑app` | Enables host‑level container management for scripts | Documented, admin‑only |
|
||
| *Offline bundle* | Tarred images + compose files for air‑gapped deployment | Offline environments cannot pull from Docker Hub | `scripts/build_docker.py` creates bundle |
|
||
| *Internal PyPI server* | Run `pypiserver` container, serve wheels offline | Remove external PyPI dependency | Implemented, UI `/pypi` added |
|
||
|
||
## Deployment‑Related Preferences (scenario level, development workspace)
|
||
|
||
1. **Language** – Daily communication in **中文** unless otherwise requested. (source: `global_guidance_memory:7429c22e-...`, `global_guidance_document:6973450e-...`)
|
||
2. **Credential Handling** – All secrets must be fetched from **Vaultwarden**; only the credential name is stored in memory. (source: `global_guidance_memory:105b328f-...`, `global_guidance_document:2b47472d-...`)
|
||
3. **FastAPI Async Pitfall** – Avoid blocking I/O inside `async def`; move to `def` or thread‑pool. (source: `global_guidance_document:e4fc35f2-...`)
|
||
4. **Docker Exec Timeout** – Disable default 3 s timeout via `socket.settimeout(None)`. (source: `global_guidance_document:e4fc35f2-...`)
|
||
5. **KISS & YAGNI** – Keep implementations minimal, no speculative dependencies. (source: `global_guidance_memory:bf88c265-...`, `global_guidance_document:2b47472d-...`)
|
||
|
||
These preferences are recorded as **scenario‑level** because the output scope is *project* and cannot promote them to global.
|
||
|
||
## Tags
|
||
|
||
`[deployment]` `[docker]` `[fastapi]` `[vue]` `[ci]` `[offline]` `[security]` |