技术栈¶
生态系统的所有平台都运行在同一套技术栈上。这并非偶然：开发者从一个仓库转到 另一个仓库时无需重新学习，安全修复也能以同一种形态推广到所有系统。
Gerege Nexus 的不同之处
Gerege Nexus 跑在同一套技术栈上（Go · chi · pgx ·
不用 ORM · Next.js App Router），但有三点不同：它是模块化单体（模块编译进
同一个二进制，并通过应用商店按租户分发）、使用 goose 做迁移，且只依赖
PostgreSQL，不用 Redis。版本：Go 1.25 · Next.js 15。
后端¶
| 组件 | 选型 |
|---|---|
| 语言 | Go 1.26 |
| HTTP | 标准库 net/http + go-chi/chi 路由 |
| 数据库 | PostgreSQL — jackc/pgx（pgxpool），手写 SQL |
| 缓存 / 会话 | Redis |
| 架构 | Clean Architecture — handler → usecase → repository → domain |
为什么不用 ORM？
数据层基于 pgx 采用手写 SQL。原因有二：可以直接使用深植于 PostgreSQL
自身的能力——行级安全（RLS）、CTE、LISTEN/NOTIFY、JSONB——而不必透过 ORM
的抽象；同时也不必去猜测最终会生成什么样的查询。
Clean Architecture 的硬性规则：不得反向引用。 业务内核（domain、usecase）
永远不会 import Web 框架。正是这一点保证了替换 HTTP 层时业务逻辑不受影响。
前端¶
| 组件 | 选型 |
|---|---|
| 框架 | Next.js 15/16，App Router |
| 模式 | BFF（Backend-for-Frontend） |
| 数据层 | TanStack Query |
这里的 BFF 是什么意思：浏览器从不直接访问后端，只与同域下的 Next.js 路由通信，再由这些路由在服务端侧代理到后端。
结果是：令牌永远不会进入客户端 JavaScript——改用 cookie 会话，XSS 也就不再是 窃取令牌的途径。在此之上还有双重 CSRF 防护：自定义请求头加 origin 校验。
移动端与桌面端¶
| 平台 | 技术 |
|---|---|
| iOS | Swift、SPM SDK（GeregeSmartID）+ 各品牌应用 |
| Android | Kotlin / Jetpack Compose SDK |
| macOS | SwiftUI RP 客户端 + USB token 套件 |
| Windows | MSIX（已签名） |
| Web RP | TypeScript SDK |
AI 流水线¶
基于 Gemini 构建，采用无 SDK 的 REST 客户端 + function calling：
- 文本与语音对话；
- STT（语音 → 文本）与 TTS（文本 → 语音）；
- 实时翻译；
- 基于 pgvector 的知识库——从代码与文档中建立索引；
- 以用户所用语言作答；无需登录的聊天挂件。
分层 system prompt：代码中硬编码的基础护栏（guardrail），加上管理员通过
数据库配置的适用范围与指令。这样助手就只会停留在既定边界之内。
search_knowledge 工具让回答立足于知识库中的真实数据，避免凭空编造。
密码学¶
签名代码是从 Java/Spring 原系统移植而来，因此必须在协议层面保持完全兼容。 这一点由冻结的 golden vectors 锁定：
- SEC1 压缩格式的 EC 点序列化；
- Java
BigInteger.toByteArray()的语义（符号字节的行为）。
Go 服务端、iOS SDK、Android SDK 三者必须产出逐字节一致的结果。
切勿删除 golden vector
golden.json 文件无法重新生成。它们是与原系统兼容性的唯一证明。修改
密码学相关代码时，必须用这些测试进行校验。
基础设施¶
| 组件 | 选型 |
|---|---|
| 容器 | Docker Compose |
| CI/CD | GitHub Actions（含自托管的 Windows/macOS runner） |
| Edge | nginx —— TLS 终止、限流、反向代理 |
| 证书 | Let's Encrypt（certbot、webroot） |
| 文档 | MkDocs Material + mkdocs-static-i18n，多语言 |
可观测性¶
- OpenTelemetry —— 分布式链路追踪；
- Prometheus —— 指标（
/metrics）； - Zap —— 结构化日志；
- 审计日志 —— 哈希链式、仅追加；仅管理员可读，并可校验完整性。
生产环境须关闭
/metrics 与 /swagger 在生产环境中由 bearer token 保护。它们会暴露
内部结构，敞开放置会带来信息泄露风险。
测试¶
- 单元测试 —— 位于业务逻辑层；
- testcontainers 集成测试 —— 对接真实的 PostgreSQL/Redis；
- golden vector 测试 —— 验证密码学兼容性。