John/system-design

Fork 0

Files

T

jiahong e303bb868a 更新

2026-03-22 15:19:22 +08:00

22 KiB

Raw Permalink Blame History

Writech ICT 服务平台规划设计及实施方案

一、概述

1.1 目标

基于公司现有 IT 服务资源（详见 IT服务资源），构建面向 2E（企业员工）、2B（合作伙伴）、2C（最终消费者） 三类用户的统一 ICT 服务平台，实现：

企业员工全线上办公
全部基础系统与业务系统统一登录，采用免密码秘钥认证
视频之外的全部业务上 SSL 安全保障
应用服务器可按需弹性扩缩
核心数据安全自主可控

1.2 基础设施概况

服务器	云平台	服务区	IP	绑定域名	定位
腾讯云应用服务器	腾讯云	广州	106.55.191.177	writech.cn	大陆数据服务，面向国内用户
阿里云应用服务器	阿里云	新加坡	47.84.109.13	writech.ai	品牌站点与海外服务
私有云应用服务器	私有云	企业	118.141.37.23	—	数据源站、用户账户信息源

1.3 核心架构原则

私有云不直面终端用户：私有云仅对应用服务器提供数据支撑（数据库、文件存储、身份源），不直接面向 2B / 2C / 2E 用户
公有云承载互联网服务：员工在线工作系统、AI 客服、商城、客户支持等全部运行在腾讯云/阿里云应用服务器上
弹性扩缩：应用服务器及其上应用可按需增减，平台架构须适应服务器动态变化

二、文档与资料管理体系

2.1 Git 仓库统一管理

企业全部文档资料均基于 Git 仓库管理和存放，涵盖以下类别：

类别	说明	典型仓库示例
原始资料	产品需求、技术方案、会议纪要	docs、project-plan
证件资料	企业证照、商标、专利、软著	certificates、IP-doc
媒体宣传资料	品牌素材、产品图片、宣传视频脚本	web-doc、media-assets
软件源代码	产品代码、固件代码、SDK 代码	各产品独立仓库
软件开发工具	构建脚本、CI/CD 配置、开发环境配置	devtools、ci-config

2.2 Git 服务部署

┌─────────────────────────────────────────────────┐
│               Git 服务 (Gitea)                   │
│          运行于：互联网应用服务器                    │
│                                                   │
│  · SSH (22/tcp)    — 代码推拉（SSH 秘钥认证）       │
│  · HTTPS (443/tcp) — Web UI（SSO 秘钥登录）        │
│  · 仓库数据存储     — 私有云 NFS/Samba 挂载         │
└─────────────────────────────────────────────────┘

Git 服务（推荐 Gitea 轻量自托管）运行在互联网应用服务器上，面向员工提供服务
仓库数据实际存储于私有云大容量存储，通过内网挂载
所有 Git 操作均通过 SSH 秘钥认证，无密码

三、统一登录与秘钥认证体系

3.1 设计目标

所有企业基础系统与业务应用必须实现统一登录，且全部采用免密码秘钥登录，杜绝密码泄露风险。在手机/移动场景下，支持微信扫码登录作为秘钥认证的等价替代——微信扫码本质上仍是秘钥认证，手机端微信持有用户凭证（OpenID），相当于手机即秘钥载体。

需纳入统一登录的系统清单：

分类	系统	认证方式
基础设施	Git (Gitea)	SSH 秘钥 + Web SSO
基础设施	Samba 文件共享	Kerberos + 秘钥
基础设施	数据库应用	客户端证书
通信协作	腾讯企业邮箱	SAML SSO 对接
开发工具	编译管理 (Jenkins/Drone)	Web SSO
开发工具	项目管理 (Redmine/Plane)	Web SSO
开发工具	测试管理	Web SSO
业务系统	技术论坛	Web SSO
业务系统	客户支持系统	Web SSO
业务系统	商城系统	Web SSO
业务系统	AI 在线客服	Web SSO

3.2 认证架构

@startuml
skinparam componentStyle rectangle
title 统一认证架构

node "私有云 (身份源)" as PCloud {
  database "OpenLDAP\n用户目录" as LDAP
  database "SSH 公钥库" as SSHKeys
}

node "互联网应用服务器" as AppServer {
  component "Keycloak\nSSO 认证中心" as KC
  component "Nginx\n反向代理" as Nginx
  component "Git / CI / 项目管理\n论坛 / 商城 / 客服" as Apps
}

cloud "微信开放平台" as WX

actor "员工 / 合作伙伴 / 消费者" as User

User -down-> Nginx : HTTPS 访问
Nginx -down-> KC : 认证请求
KC -down-> LDAP : 用户验证
KC -right-> Apps : OIDC Token
KC -left-> WX : 微信扫码认证\n(Social IdP)
User -down-> Apps : SSH 秘钥访问 (Git)
Apps -down-> SSHKeys : 公钥校验
@enduml

3.3 技术方案

身份目录：OpenLDAP

部署于私有云，作为全局唯一的用户身份源
存储员工基本信息、组织架构、角色权限
存储每个用户的 SSH 公钥（sshPublicKey 属性）
所有系统通过 LDAP 协议查询用户信息

SSO 认证中心：Keycloak

部署于互联网应用服务器，面向所有用户提供认证服务
对接 OpenLDAP 作为用户联邦（User Federation）
支持 OIDC / SAML 协议，所有 Web 应用通过标准协议接入
免密码登录实现：Keycloak 配置 WebAuthn（硬件安全秘钥/系统指纹）作为首选认证方式，禁用密码登录
微信扫码登录：Keycloak 配置微信开放平台作为 Social Identity Provider，支持扫码登录作为秘钥认证的移动端替代

免密码秘钥登录的三种场景

场景	方式	秘钥载体	说明
SSH 类服务（Git 推拉、服务器运维）	SSH 秘钥对（Ed25519）	电脑本地 `~/.ssh/`	用户本地生成秘钥对，公钥注册到 LDAP，私钥留在本地
Web 类服务 — 电脑端	WebAuthn 硬件秘钥 / 系统生物识别	硬件秘钥 / 电脑	用户注册硬件秘钥（如 YubiKey）或系统指纹/面容到 Keycloak
Web 类服务 — 移动端	微信扫码登录	手机微信	手机扫描 Keycloak 登录页二维码，微信 OpenID 映射到 LDAP 用户

设计要点：三种方式本质均为秘钥认证——SSH 秘钥存于电脑、WebAuthn 秘钥存于硬件/系统、微信凭证存于手机。三者绑定到同一 LDAP 身份，互为替代，用户按使用场景选择最便捷的方式。

微信扫码登录与秘钥认证的绑定关系

微信扫码登录并非独立的认证体系，而是秘钥认证在移动场景下的延伸：

┌──────────────────────────────────────────────────────┐
│                  同一 LDAP 身份                        │
│           (zhangsan@writech.cn / DN)                   │
│                                                        │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│   │  SSH 秘钥    │  │  WebAuthn   │  │  微信扫码    │  │
│   │  Ed25519    │  │  FIDO2 秘钥  │  │  OpenID 绑定 │  │
│   │             │  │             │  │             │  │
│   │ 载体：电脑   │  │ 载体：硬件   │  │ 载体：手机   │  │
│   │ 场景：CLI   │  │ 场景：PC浏览器│  │ 场景：移动端  │  │
│   └─────────────┘  └─────────────┘  └─────────────┘  │
│                                                        │
│   三种秘钥绑定在同一身份上，禁用 LDAP 账户后全部失效       │
└──────────────────────────────────────────────────────┘

技术实现：

Keycloak 配置微信 Social IdP：在 Keycloak 管理后台添加「微信开放平台」作为 Identity Provider，配置 AppID 和 AppSecret
OpenID 绑定：员工首次使用时，先通过 WebAuthn 登录 Keycloak，在账户设置中「关联社交账号 → 微信」，扫码完成绑定。此后微信 OpenID 与 Keycloak 用户（即 LDAP 身份）建立 1:1 映射
登录流程：Keycloak 登录页显示「微信扫码登录」按钮 → 用户手机微信扫码 → 微信返回 OpenID → Keycloak 查找绑定的 LDAP 用户 → 校验 LDAP 账户状态（未禁用）→ 签发 OIDC Token → 登录成功
安全保障：LDAP 账户一旦禁用，即使微信 OpenID 绑定仍存在，Keycloak 在 Token 签发前会验证 LDAP 状态，登录请求将被拒绝

腾讯企业邮箱对接

企业邮箱域名：@writech.cn
通过 Keycloak SAML IdP 对接腾讯企业邮箱的 SSO 登录
员工在 Keycloak 完成秘钥认证后，自动获得企业邮箱访问权

四、SSL 安全策略

4.1 覆盖范围

服务类型	SSL 策略	说明
Web 应用（全部）	强制 HTTPS	包括 Git Web UI、SSO、论坛、商城、客服等
API 接口（全部）	强制 HTTPS	所有 RESTful / WebSocket / MQTT-over-WSS
SSH 服务	SSH 协议自带加密	Git 推拉、服务器运维
邮件服务	TLS 加密	腾讯企业邮箱原生支持
视频流服务	豁免	实时视频流对延迟敏感，按需采用 SRTP 或不加密

4.2 证书方案：ZeroSSL + acme.sh 自动续期

全部服务器的 SSL 证书统一采用 ZeroSSL 免费通配符证书，由 writech.hk 服务器集中管理：

签发工具：acme.sh + ZeroSSL ACME 接口
证书类型：DV 通配符（*.writech.cn、*.yink.ai、*.writech.ai、*.writech.hk）
DNS 验证：.ai / .hk 域名通过阿里云 DNS API（dns_ali），.cn 域名通过腾讯云 DNSPod API（dns_dp）
自动续期：cron 每日检查，到期前 30 天自动续期
自动分发：续期后通过 SCP 推送至全部应用服务器，自动 reload Nginx

4.3 新增应用服务器的证书部署

当按需新增应用服务器时，证书部署流程：

在 writech.hk 的分发脚本（deploy_certs.sh）中添加新服务器地址
配置 writech.hk 到新服务器的 SSH 免密登录（ssh-copy-id）
手动触发一次分发或等待下次 cron 自动续期时同步
新服务器 Nginx 配置引用标准证书路径（/etc/ssl/certs/、/etc/ssl/private/）

五、业务应用系统规划

5.1 系统部署总览

全部业务应用运行于互联网应用服务器（腾讯云 / 阿里云），私有云仅提供数据后端支撑：

系统	用户群体	部署位置	说明
Git 代码托管 (Gitea)	2E	互联网应用服务器	企业文档与代码管理
SSO 认证中心 (Keycloak)	2E / 2B / 2C	互联网应用服务器	全局统一登录
编译管理 (CI/CD)	2E	互联网应用服务器	自动构建、自动部署
项目管理	2E	互联网应用服务器	任务跟踪、迭代管理
测试管理	2E	互联网应用服务器	测试用例、缺陷跟踪
技术论坛	2E / 2B	互联网应用服务器	技术交流、知识沉淀
Samba 文件共享	2E	互联网应用服务器	公共文件共享（VPN 接入）
企业邮箱	2E	腾讯企业邮箱 (SaaS)	@writech.cn 统一邮箱
AI 在线客服	2B / 2C	互联网应用服务器	基于 AI 基础能力的智能客服
客户支持系统	2B / 2C	互联网应用服务器	工单、FAQ、文档中心
商城系统	2C	互联网应用服务器	产品展示、在线购买

5.2 AI 在线客服

部署于互联网应用服务器，直接面向 2B / 2C 用户
基于云平台 AI 算力 API（腾讯云/阿里云 NLP、大模型接口）构建
功能：智能问答、产品咨询、售后引导、工单自动分派
知识库数据存储于私有云，AI 服务通过内网调取

5.3 员工在线工作系统

员工全线上办公，核心工具链均运行在互联网应用服务器上：

员工日常工作流
  ├─ Git     — 文档编写、代码开发、版本管理
  ├─ CI/CD   — 代码编译、自动测试、自动部署
  ├─ 项目管理 — 任务分派、进度跟踪、迭代规划
  ├─ 测试管理 — 用例编写、测试执行、缺陷跟踪
  ├─ 论坛    — 技术讨论、方案评审、知识分享
  ├─ 邮箱    — 对外沟通、商务协作
  └─ Samba   — 共享大文件（设计稿、固件包等）

六、弹性扩缩策略

6.1 应用服务器动态管理

应用服务器及其上部署的应用会按需增减，平台设计须适应此动态变化：

新增服务器流程

资源开通：在腾讯云/阿里云开通新云服务器实例
基础配置：安装 Nginx、Docker 等基础环境
接入认证：配置 Keycloak OIDC 客户端，接入统一登录
证书部署：在 writech.hk 分发脚本中添加新服务器，同步 SSL 证书
DNS 解析：按需添加子域名解析记录
应用部署：部署业务应用容器
Nginx 反代：配置反向代理和 SSL 终止
注册到 LDAP：如有新服务角色，在 LDAP 中添加对应服务条目

缩减服务器流程

业务迁移：将应用和数据迁移至其他服务器
DNS 摘除：删除或更新相关 DNS 记录
证书脚本清理：从 deploy_certs.sh 中移除该服务器
Keycloak 清理：删除对应 OIDC 客户端配置
资源释放：销毁云服务器实例

6.2 配置即代码

所有服务器配置、部署脚本、Nginx 配置均纳入 Git 仓库管理，确保：

新服务器可通过脚本快速初始化
配置变更有版本记录，可回溯可审计
服务器增减时只需修改配置文件并执行部署脚本

七、账户生命周期管理

7.1 员工入职 — 开通账户

@startuml
skinparam componentStyle rectangle
title 员工入职账户开通流程

start
:IT管理员在 OpenLDAP 创建用户账户;
note right: 填写姓名、邮箱、部门、角色
:分配 @writech.cn 企业邮箱;
note right: 腾讯企业邮箱后台创建

:员工在个人电脑生成 SSH 秘钥对;
note right
  ssh-keygen -t ed25519 -C "name@writech.cn"
  生成 ~/.ssh/id_ed25519 (私钥)
  和 ~/.ssh/id_ed25519.pub (公钥)
end note

:员工将公钥提交给 IT 管理员;
note right: 通过企业邮箱发送或内部系统上传

:IT管理员将公钥注册到 LDAP;
note right: 写入用户的 sshPublicKey 属性

:员工注册 WebAuthn 硬件秘钥/生物识别;
note right
  登录 Keycloak 自助注册页面
  插入 YubiKey 或使用系统指纹/面容
  完成 WebAuthn 绑定
end note

:员工绑定微信扫码登录;
note right
  在 Keycloak 账户设置中
  选择 "关联社交账号 - 微信"
  手机微信扫码完成 OpenID 绑定
  此后可用微信扫码替代 WebAuthn 登录
end note

:账户开通完成;
note right
  可访问：Git、CI/CD、项目管理、
  测试管理、论坛、邮箱、Samba
  认证方式：SSH秘钥 / WebAuthn / 微信扫码
end note
stop
@enduml

7.2 SSH 秘钥管理规范

秘钥生成要求

项目	要求
算法	Ed25519（推荐）或 RSA 4096
口令保护	私钥必须设置本地口令（passphrase）
存储位置	私钥仅存于员工本人电脑 `~/.ssh/` 目录
备份	私钥禁止上传到云盘或共享目录；建议加密备份到个人 U 盘

公钥注册流程

员工本地执行 ssh-keygen -t ed25519 -C "name@writech.cn" 生成秘钥对
将 ~/.ssh/id_ed25519.pub 内容通过安全渠道提交给 IT 管理员
IT 管理员通过 LDAP 管理工具将公钥写入该用户条目
写入后，员工即可通过 SSH 秘钥访问 Git、服务器等全部 SSH 类服务
员工登录 Keycloak 自助页面，注册 WebAuthn 设备用于 Web 类服务
员工在 Keycloak 账户设置中关联微信账号（扫码绑定 OpenID），作为移动端登录的替代方式

7.3 员工电脑更换 — 秘钥迁移

推荐方案：生成新秘钥

在新电脑上重新生成新的 SSH 秘钥对
将新公钥提交给 IT 管理员
IT 管理员在 LDAP 中追加新公钥（保留旧公钥，过渡期并存）
员工在新电脑验证全部系统可正常访问
IT 管理员删除旧公钥
在 Keycloak 中注册新电脑的 WebAuthn 设备

注意：微信扫码登录绑定与电脑无关（绑定在手机微信上），更换电脑不影响微信扫码登录。

紧急方案：迁移旧秘钥

若需立即使用且来不及走流程：

通过加密 U 盘将旧电脑 ~/.ssh/ 目录中的私钥文件拷贝到新电脑
确认拷贝后，立即安全擦除 U 盘中的秘钥文件
在新电脑验证连接正常
建议后续仍重新生成秘钥并替换，降低私钥泄露风险

7.4 员工离职 — 权限回收

离职权限回收必须在员工最后工作日当天完成，流程如下：

@startuml
skinparam componentStyle rectangle
title 员工离职权限回收流程

start
:HR 通知 IT 管理员离职日期;

:IT管理员禁用 LDAP 账户;
note right
  禁用后即时生效：
  · SSH 秘钥认证失败（公钥已不可用）
  · Web SSO 登录失败（LDAP 拒绝验证）
  · 全部系统同步失效
end note

:删除 Keycloak 中该用户的 WebAuthn 设备
及微信 OpenID 绑定;

:在腾讯企业邮箱后台停用邮箱;
note right: 邮箱数据保留 90 天备查后删除

:回收企业设备（如有 YubiKey）;

:从 LDAP 中删除用户公钥;

if (该员工有服务器 root/sudo 权限?) then (是)
  :检查并轮换相关服务器的 deploy key;
  :审计该员工最近操作日志;
endif

:归档离职员工资料;
:权限回收完成;
stop
@enduml

关键要点

LDAP 禁用即全局失效：由于所有系统的认证源都是 LDAP，禁用 LDAP 账户后，该员工立即无法访问任何系统，无需逐个系统处理
企业邮箱独立处理：腾讯企业邮箱为 SaaS 服务，需在腾讯后台单独停用
秘钥残留无害：即使离职员工仍持有私钥，由于公钥已从 LDAP 删除，私钥无法通过任何系统验证
微信绑定同步失效：LDAP 账户禁用后，Keycloak 在微信扫码回调时会校验 LDAP 状态，拒绝签发 Token，无需单独解绑微信（但建议清理绑定记录）
特权账户审计：对拥有 root/sudo 权限的离职员工，需额外审计操作记录并轮换相关 deploy key

八、系统部署拓扑

@startuml
skinparam componentStyle rectangle
title ICT 服务平台部署拓扑

node "阿里云 [新加坡]\nwritech.ai · 47.84.109.13" as ACloud {
  component "Nginx + SSL" as ANginx
  component "品牌官网" as Web
  component "海外业务服务" as Overseas
}

cloud "互联网用户" as Users {
  actor "2E 企业员工" as E
  actor "2B 合作伙伴" as B
  actor "2C 最终消费者" as C
}

node "腾讯云 [广州]\nwritech.cn · 106.55.191.177" as TCloud {
  component "Nginx + SSL" as TNginx
  component "Keycloak SSO" as SSO

  package "员工工作系统" {
    component "Git (Gitea)" as Git
    component "CI/CD" as CICD
    component "项目管理" as PM
  }

  package "对外业务系统" {
    component "AI 在线客服" as AICust
    component "商城 / 客户支持" as Biz
  }
}

node "私有云 [数据后端]\n118.141.37.23" as PCloud {
  database "OpenLDAP\n身份目录" as LDAP
  database "SSH 公钥库" as Keys
  database "核心数据库" as DB
  storage "Git 仓库存储\nSamba 文件存储" as Store
}

node "writech.hk · 证书管理中心" as HK {
  component "acme.sh + ZeroSSL" as ACME
}

' == 用户 → 阿里云（向上） ==
C -up-> ACloud : HTTPS
E -up-> ACloud

' == 用户 → 腾讯云（向下） ==
E -down-> TCloud : SSH / WebAuthn / 微信扫码
B -down-> TCloud : WebAuthn / 微信扫码 / API
C -down-> TCloud : WebAuthn / 微信扫码

' == 应用 → 数据后端 ==
SSO -down-> LDAP : 用户认证
Git -down-> Keys : 公钥校验
Git -down-> Store : 仓库数据
CICD -down-> Store
AICust -down-> DB : 知识库
Biz -down-> DB : 业务数据

' == 证书分发（虚线） ==
ACME ..> TNginx : 证书分发
ACME ..> ANginx : 证书分发
@enduml

九、实施路线图

阶段	任务	预计周期
第一阶段：基础设施	私有云部署 OpenLDAP，建立用户目录	第 1 周
第一阶段	互联网服务器部署 Keycloak，对接 LDAP	第 1-2 周
第一阶段	SSL 证书全覆盖（ZeroSSL + acme.sh 已就绪）	第 1 周
第一阶段	部署 Git (Gitea)，配置 SSH 秘钥认证 + SSO	第 2 周
第二阶段：核心系统	部署 CI/CD、项目管理、测试管理，接入 SSO	第 3-4 周
第二阶段	部署 Samba 文件共享，对接 LDAP 认证	第 3 周
第二阶段	腾讯企业邮箱 SAML SSO 对接	第 3 周
第二阶段	制定并发布员工秘钥管理规范	第 3 周
第三阶段：业务系统	部署技术论坛、客户支持系统，接入 SSO	第 5-6 周
第三阶段	部署商城系统，接入 SSO	第 5-6 周
第三阶段	部署 AI 在线客服，对接云平台 AI API	第 6-8 周
第四阶段：运营优化	弹性扩缩自动化脚本开发	按需
第四阶段	全系统安全审计与渗透测试	按需

22 KiB Raw Permalink Blame History Unescape Escape