Gerege Nexus¶

Gerege Eco System · 私有平台

Gerege Nexus 连接 Gerege Eco System 的机构、服务和用户。仅限已获授权的用户访问。eID 用于验证身份，访问权限由机构管理员授予。

Gerege Nexus 是 Go 后端、Next.js web shell、PostgreSQL 数据库、运营方 control plane 以及 native 客户端的基础。业务应用由 distribution 仓库以编译期 Go 模块的形式加入。本基础仓库并不是面向所有行业的现成 ERP 套件。

实际范围（2026-10-25）： catalog/apps.json 为空——核心不携带任何业务应用；每个应用都来自发行版的目录。最后一个应用 io.gerege.nexus.sso_clients 已于 2026-08-25 迁移到 appstore-gerege-nexus，任何 distribution 都从应用商店获取它。Contacts、products、inventory、billing、 documents、government workflow、SSO 客户端等应用的 migration history 或 frontend translation 可能仍留在本仓库中，但它们的可运行模块不在本基础二进制文件中。此类应用的路由在本 deployment 上不会开放。

Монгол · العربية · 中文 · English · Français · Русский · Español

本仓库究竟包含什么¶

部分	当前实现
Tenant plane	登录、session、tenant membership、RBAC、profile、应用安装/关闭、AI API、设备、email verification、SSO client/provider、reporting engine
Operator plane	租户 lifecycle、运营方 TOTP 登录、audit、support、quota/metering、feature flag、runtime settings/credentials、announcement、backup/deploy 管理
内置应用	无。每个应用都通过目录提供——2026-08-25 `sso_clients` 迁出后，本二进制文件不包含任何业务应用
Web	Public landing、login/setup、profile、app store、settings、control plane——全部基于 `@gerege-systems/ui`（Tailwind 4）；应用界面（SSO 客户端、文档、联系人）在没有模块的情况下以无效状态留在 shell 中
Native	macOS、iOS/iPadOS、Windows、Android shell；Linux 使用 PWA
Observability	`/health`、`/ready`、`/metrics`、structured log、可选 OTLP/Sentry；独立的 monitoring compose

基础平台中存在路由、表或 service，并不意味着一定有面向用户的业务应用。编译期模块只有在实现了 pkg/nexus 的 contract、注册进 binary、收录进目录并安装到该 tenant 时，模块路由才会生效。

本基础二进制文件中不包含的内容¶

Contacts、products、inventory、billing 业务应用
Organisation & People 的部门/员工应用（但机构的 legal profile 仍作为平台的一部分保留在 /organisation）
Documents 后端模块、report UI。本仓库中有 contract/inbox 的可选前端 client，但与之匹配的 contract API 目前在 base 和 client-gerege-nexus distribution 中均尚不存在；若 endpoint 实际不响应，landing 上不会显示其链接
Government services workflow UI/模块
整个 Өртөө（驿站）——面板、通道、peer/exchange API、封套 contract。2026-08-27 最后一部分迁移到了 client-gerege-nexus
外部系统连接器与 webhook（Google Drive、Dropbox、Meet、订阅方 URL）。同样于 2026-08-27 迁出；核心中只保留了凭据密封加密（nexus.SecretSealer）。自动向外发送已签名文档的行为也已从核心中移除
通用 adaptive circuit breaker、singleflight、generic retry engine

其中部分内容已拆分到 product distribution 仓库。模块如何编写以及如何通过目录提供，请参阅 docs/MODULES.md；distribution 如何获取并更新核心，请参阅 docs/DISTRIBUTION.md；当前架构请参阅 docs/ARCHITECTURE.md。

核心能力¶

编译期模块 SDK：route、permission、menu、dependency、migration、 report、AI tool 以及 capability contract。
每个 tenant 的 app installation 与 RBAC gate。未安装/已停用的模块路由返回 403。
本地目录或 Ed25519 签名的远程目录；cache fallback 以及 manual/background sync。
Password、eID、ДАН（DAN）、Google 以及 upstream OIDC 登录；同时提供 OAuth2/OIDC provider。
PostgreSQL 的 workspace、registry、operator schema，RLS/role 防护。
配置 Redis 时实现副本间 cache invalidation 与 shared rate limit；未配置时使用 single-process fallback。
并发请求的 load shedding。每个外部 client 都有各自的 timeout/retry 策略；不应将并不存在的 generic circuit breaker 视为平台已具备。
配置 Gemini 密钥时提供 chat、speech-to-text、text-to-speech、translation。业务数据的 AI tool 由 distribution 模块自行注册；基础 deployment 不会编造并返回 inventory 或 billing 数字。
设计系统：web shell 与控制台基于 @gerege-systems/ui，token 的唯一来源是该库的 theme.css。每个 deployment 无需修改代码，即可通过 BRAND_THEME_* 环境变量以及 ui.gecore.mn/#theme 的“Get code” CSS 更改外观（DEVELOPMENT.md）。
平台内置 E-ID、ДАН（DAN）、ХУР（XYP）客户端。在 production 环境中 mock 默认关闭；使用真实服务需要各自的 credential。

仓库结构¶

backend/
  cmd/                  api、migrate、bootstrap、catalog 工具
  db/migrations/        基础 PostgreSQL 迁移
  internal/kernel/      三个 plane 共用的底层机制
  internal/operator/    deployment/operator plane
  internal/workspace/   代表组织运行的 plane
  internal/person/      个人自己的空间 — /api/v1/me
  internal/apps/        distribution module 的装配点（目前为空）
  pkg/nexus/            distribution module 的公共 SDK
  pkg/host/             启动 distribution binary 的公共入口
frontend/               Next.js web shell 与 control plane UI
catalog/                基础 catalog、manifest、chronicle
native-apps/            macOS、iOS/iPadOS、Windows、Android 客户端
deploy/                 image, compose, nginx, monitoring
docs/                   当前、历史与提案文档的索引

运行¶

环境要求¶

Docker Compose，或
Go 1.26+、Node.js 20+、PostgreSQL 16+

Docker Compose¶

docker compose up -d
docker compose ps

Compose 会启动 PostgreSQL、Redis、一次性 migration、backend 和 frontend。使用以下地址：

Tenant web：http://nexus.localhost:3000
Control plane web：http://admin.localhost:3000
API health：http://localhost:8080/health

Development demo account：

字段	值
邮箱	`admin@example.com`
密码	`Password123!`
租户	`Demo Corporation`（`demo`）

SEED_DEMO_DATA 在 production 以外的环境中默认启用。在 production 中，未显式设置为 true 时不会创建 demo account。

手动运行¶

先启动 PostgreSQL（如需要，再启动 Redis），然后：

cd backend
go mod download
DATABASE_URL="postgres://postgres:postgrespassword@localhost:5432/platform_db?sslmode=disable" \
  go run ./cmd/migrate up

PUBLIC_ORIGIN=http://nexus.localhost:3000 \
ALLOWED_ORIGINS=http://nexus.localhost:3000,http://admin.localhost:3000 \
CONTROL_PLANE_HOST=admin.localhost \
  go run ./cmd/api

在另一个 terminal 中：

cd frontend
npm ci
CONTROL_PLANE_HOST=admin.localhost \
NEXT_PUBLIC_API_URL=http://nexus.localhost:8080/api/v1 \
NEXT_PUBLIC_CONTROL_PLANE_API_URL=http://admin.localhost:8080/api/platform/v1 \
  npm run dev

不要从 README 推测 production 配置。完整变量与安全 default 请参照 .env.example，运行中部署的配置请参照 proxmox-gerege-net (stack/nexus)，创建首个 tenant/operator 的步骤请参照 docs/OPERATIONS.md。

API 与目录的权威来源¶

README 中的 API 列表并非完整 contract。与代码一同校验的来源：

Platform route snapshot： backend/pkg/host/testdata/routes.txt
Module SDK public API snapshot： backend/pkg/nexus/testdata/api.txt
Base catalog：catalog/apps.json（仅 API 网关）
Module SDK 的 SSO contract： backend/pkg/nexus/ssoclients.go
配置：.env.example

基础 public endpoint 包括 /health、/ready、/metrics、auth、setup、 OAuth2/OIDC、app store、device enrollment、email verification。需要 tenant session 的路由、control plane 路由、模块路由分别受到各自的保护。

测试¶

cd backend
go test ./...
go vet ./...

cd ../frontend
npm ci
npm test
npm run lint
npm run build

CI 在此基础上增加 migration-backed race test、API/route boundary、PWA、host、 translation-gap report、Docker build、govulncheck、gosec 以及 native client build。实际运行的命令请参阅 .github/workflows/ci.yml、 security.yml、 native-clients.yml。

语言与文档状态¶

UI 的源字符串为蒙古语和英语；另有阿拉伯语、中文、法语、俄语、西班牙语 overlay。缺失的 overlay 会 fallback 到英语，CI 会报告缺口——不承诺所有界面 100% 已翻译。

README 提供七种语言。并非每份技术文档都有七种译本；每个文件的语言与状态记录在 docs/README.md 中。名称含 PLAN、 PROPOSAL、PROMPT、WORKLOG 的文件不是当前的 runtime contract。在运行说明中不得单独将其作为权威来源。

安全与项目状态¶

请勿在 public issue 中公开漏洞；请使用 SECURITY.md 中的 private reporting 流程。