# CodeLInk

**Repository Path**: heavenly-number/efficiency-management-system

## Basic Information

- **Project Name**: CodeLInk
- **Description**: 使用C++设计并实现了一个前后端分离的多用户在线程序交流分享平台，采用微服务架构，包含Qt客户端、HTTP网关服务器和多个gRPC微服务。
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-13
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeLink — 模块化协作与即时通信基座

CodeLink 由三部分组成：一个 C++ 高并发 HTTP/WebSocket **Gateway**、一组按模块组合的
**Go 业务服务**（community / messaging / social / media / catalog / verify）、以及一个
**Qt 桌面客户端**。整套栈以容器交付，由 CI 九阶段流水线构建、验证并推送到预生产环境。

> 一句话定位：这是一个**按 composition 组合、可验证、可回滚**的微服务基座 ——
> 不是单点 demo，也不是"什么都能开"的一体化服务。
>
> 本文档是**现行事实来源**之一。历史文档已归档，见 [docs/archive/README.md](docs/archive/README.md)。

---

## 1. 当前拓扑

```mermaid
graph LR
    QT["Qt 桌面客户端<br/>view/"]
    EDGE["tianshucode-edge<br/>nginx（独立容器）"]
    GW["gateway<br/>C++ HTTP/WS 入口"]
    COMM["community-rpc<br/>Go"]
    MSG["messaging-rpc<br/>Go"]
    SOCIAL["social-rpc<br/>Go（参见 §2）"]
    KC["keycloak + keycloak-db<br/>OIDC 身份提供方"]
    MYSQL[("mysql")]
    REDIS[("redis")]

    QT -->|HTTPS| EDGE
    EDGE -->|proxy_pass| GW
    GW -->|gRPC + 内部身份校验| COMM
    GW -->|gRPC + 内部身份校验| MSG
    GW -.->|设计态| SOCIAL
    GW -->|OIDC JWT 校验| KC
    COMM --> MYSQL
    MSG --> MYSQL
    GW --> REDIS
    KC --> MYSQL
```

网关不直连业务库：业务查询走各服务的 gRPC 契约。
身份走 OIDC，Gateway 校验 `iss` / `aud` / `sub` / 租户与权限 claim，不读宿主账号库。

## 2. 生产 composition 是 10 个服务

`community-chat-desktop` 是生产使用的 composition，模块集是 5 个模块
（`codelink.platform`、`codelink.identity-adapter`、`codelink.community`、`codelink.messaging`、
`codelink.social`），`compose render` 渲染出来是 **10 个服务**：`gateway`、`community-rpc`、
`messaging-rpc`、`platform-rpc`、`social-rpc`、`mysql`、`redis`、`minio`、`keycloak`、
`keycloak-db`。

`codelink.social` 于 **2026-09-28 按其自身要求立正**：2026-09-19 那次"把 social 移出生产"的
降级裁决写明要按带容量规划的独立立项推进，四项评估（内存、库、备份面、回滚面）已在
`docs/backend/2026-09-28-social-立项评估.md` 补齐并撤销该裁决。代价是诚实的：任何部署
`community-chat-desktop` 的地方都必须同时起 `social-rpc`，dev 栈也一样。

> **验收记录已按真实部署回填**：2026-10-05 在 124 上走完一次**真实激活**
> （候选 `21087d44` / run `3293950`：10 容器、`/api/ready` 全模块 ready、`doctor` PASS），
> `modules/manifests/runtime-acceptance.json` 的 `community-chat-desktop` 更新为 10 服务 / 5 模块，
> `codelinkctl up` 不再以 `runtime_acceptance_services_mismatch` / `..._compose_plan_mismatch`
> fail-closed。详见 [ARCHITECTURE.md §10](ARCHITECTURE.md) 与 `docs/LOCAL_DEV.md`。

## 3. 目录结构（受跟踪的顶层）

| 路径 | 作用 |
|---|---|
| `gateway/` | C++ HTTP/WebSocket 网关（composition 路由、OIDC、RBAC、ready/metrics/drain） |
| `common/` | 网关与服务共享的 C++ 组件 |
| `platform/` | 平台级 C++ 能力（身份适配、TLS、信任边界） |
| `services/` | Go 业务服务：`community` / `messaging` / `social` / `verify-server` |
| `modules/` | 模块清单与 composition 定义（`manifests/`） |
| `schemas/` | 模块清单等 JSON Schema |
| `deploy/compose/` | 可选组合的 Compose 契约（见该目录 README） |
| `deploy/production/` | 生产用 Keycloak realm 模板等 |
| `database/` | DDL 包与执行计划（下游消费者，真源见 §6） |
| `sql/review/v2` | **数据库 DDL 真源** |
| `docker/` | 镜像构建：`Dockerfile.modular-build`、`Dockerfile.service-runtime` |
| `tools/codelinkctl/` | 本地栈编排 CLI（见其 README） |
| `scripts/ci/` | CI 各阶段脚本 |
| `.workflow/` | Gitee Go 流水线定义 |
| `tests/` | C++ 单测/合约测 + Python 回归套件 |
| `view/` | Qt 桌面客户端 |
| `docs/` | 现行文档；历史文档在 `docs/archive/` |

## 4. 快速开始

三条路径，按你要的深度选。**先看 [docs/LOCAL_DEV.md](docs/LOCAL_DEV.md)**，
那里有实测耗时、每步期望输出，以及起栈的已知阻塞。

### 路径 A：证明代码干净（约 7 分钟，零前置依赖）

```bash
docker build --file docker/Dockerfile.modular-build \
  --build-arg CODELINK_COMPOSITION_FLAVOR=community-chat-desktop -t codelink/modular-build:check .
```

镜像内自带 `ctest` 与 flavor 符号断言。成功意味着：构建通过、17 个 C++ 测试全绿、
生产镜像里不存在被排除模块的符号。

### 路径 B：走一遍本地编排校验（约 2 分钟，不启动容器）

```bash
python tools/codelinkctl/codelinkctl.py init \
  --instance-dir .local/dev --composition community-chat-desktop --project-name codelink-dev
# 按 init 的输出替换 .env 里的 REQUIRED_*（含 OIDC 五项），再：
python tools/codelinkctl/codelinkctl.py config validate --instance-dir .local/dev
python tools/codelinkctl/codelinkctl.py compose render \
  --composition community-chat-desktop --instance-dir .local/dev --dev-ports
python tools/codelinkctl/codelinkctl.py doctor --composition community-chat-desktop --static
```

### 路径 C：真正把栈跑起来

需要**已存在的、按摘要/ID 固定的镜像集**（`codelinkctl up` 拒绝拉取镜像），
且当前 `runtime-acceptance.json` 的绑定与最新代码不一致 —— 见
[docs/LOCAL_DEV.md](docs/LOCAL_DEV.md) 的"起栈前置与已知阻塞"。
可复现的重路径是 `scripts/acceptance/run_community_oidc_keycloak.sh`
（建镜像、建库、起栈、负向矩阵与证据收口）。

## 5. 端口与探针

| 用途 | 地址 |
|---|---|
| Gateway HTTP | `127.0.0.1:8080`（开发 overlay 默认 `18190`） |
| Gateway 探针 | `/api/ping`、`/api/health`、`/api/ready`、`/api/metrics` |
| Gateway 生命周期 | `GET /api/build`、`POST /api/drain`（需 `lifecycle_token` Bearer） |
| Keycloak | `127.0.0.1:18086`（开发 overlay 默认 `18196`），管理端口 9000 |
| MySQL / Redis | 仅在内部网络，**不发布宿主端口**（开发 overlay 也只发布 Gateway 与 Keycloak） |

## 6. 数据层

- **DDL 真源是 `sql/review/v2`**。`database/packages/` 是它的下游消费者：
  按字节流 + `DDL_MANIFEST.sha256` 固定，规划器在产出计划前校验两者。
- 数据库变更是**独立审批路径**：`codelinkctl db plan` 出计划 → 人审 → `db apply-local`
  （只接受 `--empty-target`，不接受任何 DSN / 主机 / 口令参数）。
- 网关侧不持有业务库凭据；业务查询经各服务的 gRPC 契约。

## 7. CI 与门禁

两条 Gitee Go 流水线（定义在 `.workflow/`）：

| 流水线 | 触发 | 阶段 |
|---|---|---|
| `rc8-branch-gate.yml` | push 到 `codex/`、`feature/` 前缀的分支 | 2 段：runner canary、Linux 质量门禁 |
| `rc8-release-pipeline.yml` | push 到 `master` | **9 段**，见下 |

`rc8-release-pipeline.yml` 阶段 1–4 自动、**5–9 是人工闸门**（`trigger: manual`），
需要在构建详情页点"手动执行"：

1. Runner capacity canary（auto）
2. Linux C++ Go Compose gates（auto）
3. Build immutable candidate（auto）
4. Supply-chain gates（auto：SBOM、Trivy、cosign 签名与校验、secret scan、证据清单）
5. 121 打包预生产候选（**manual**）
6. 121 探活并传输到 124 受限入口（**manual**）
7. 124 部署状态机 dry-run（**manual**，`activation_enabled=false`、`mutation=none`）
8. 124 复验部署状态（**manual**）
9. 124 收口预生产证据（**manual**）

`activate` 从未在 CI 中执行；是否放行启用是人工裁决。

## 8. 历史与退路

旧的原生五服务栈（`boosttest` / `StatusServer` / `ChatServer1` / `ChatServer2`）与
旧部署路径（根 `docker-compose.yml`、`deploy/docker-compose.linux.yml`、`nginx/`、
`sql/init.sql` 等）已分两次退役（PR #1 部署路径、PR #2 源码栈）。

**可回滚退路**：Git 标签 `legacy-final`（`960cbce8c09761a7469920b742a037167f632d26`）
+ 离线 `git bundle`（sha256 `F04261FE07A36BCF0042C873E57907022E097B01753FCF2DA7C3579C779EE533`）。
恢复方式与语义变化见 [docs/legacy-retirement.md](docs/legacy-retirement.md)。

## 9. 推荐阅读

| 文档 | 内容 |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | 服务边界、链路、composition × 模块矩阵、已知缺口 |
| [docs/LOCAL_DEV.md](docs/LOCAL_DEV.md) | 本地栈从零到可验证，含实测耗时与阻塞说明 |
| [DEPLOY.md](DEPLOY.md) | 真实部署路径：121 构建 → CI 九阶段 → 124 受限通道 |
| [docs/文档导航.md](docs/文档导航.md) | 文档总入口 |
| [tools/codelinkctl/README.md](tools/codelinkctl/README.md) | 本地编排 CLI 的完整语义与安全边界 |
| [deploy/compose/README.md](deploy/compose/README.md) | Compose 契约与服务选择规则 |
| [docs/legacy-retirement.md](docs/legacy-retirement.md) | 两次退役删了什么、怎么回滚 |

## 10. 二次开发约定

1. 新能力先落到**模块清单**（`modules/manifests/`），再写代码；composition 是组合，不是分支。
2. 新增 HTTP 路由要同步补 composition 路由契约、RBAC 权限点与 metrics。
3. 跨服务调用统一走 gRPC 契约与内部身份校验，不新增裸内部接口。
4. 数据表变更走 `sql/review/v2` + `database/packages` 审批路径，不手改生产库。
5. 改动构建系统后必须用 `docker/Dockerfile.modular-build` 在**目标 flavor** 上验证 ——
   它自带 ctest 与符号断言，是唯一可信的构建证据。