This commit is contained in:
jiahong
2026-03-22 15:19:22 +08:00
parent e6db29485b
commit e303bb868a
6 changed files with 3462 additions and 103 deletions
@@ -0,0 +1,526 @@
# Writech ICT 服务平台规划设计及实施方案
## 一、概述
### 1.1 目标
基于公司现有 IT 服务资源(详见 [IT服务资源](../IT资源/IT服务资源.md)),构建面向 **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 UISSO 秘钥登录) │
│ · 仓库数据存储 — 私有云 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 认证架构
```plantuml
@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 账户后全部失效 │
└──────────────────────────────────────────────────────┘
```
**技术实现**
1. **Keycloak 配置微信 Social IdP**:在 Keycloak 管理后台添加「微信开放平台」作为 Identity Provider,配置 AppID 和 AppSecret
2. **OpenID 绑定**:员工首次使用时,先通过 WebAuthn 登录 Keycloak,在账户设置中「关联社交账号 → 微信」,扫码完成绑定。此后微信 OpenID 与 Keycloak 用户(即 LDAP 身份)建立 1:1 映射
3. **登录流程**:Keycloak 登录页显示「微信扫码登录」按钮 → 用户手机微信扫码 → 微信返回 OpenID → Keycloak 查找绑定的 LDAP 用户 → 校验 LDAP 账户状态(未禁用)→ 签发 OIDC Token → 登录成功
4. **安全保障**: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 APIdns_ali),.cn 域名通过腾讯云 DNSPod APIdns_dp
- **自动续期**:cron 每日检查,到期前 30 天自动续期
- **自动分发**:续期后通过 SCP 推送至全部应用服务器,自动 reload Nginx
### 4.3 新增应用服务器的证书部署
当按需新增应用服务器时,证书部署流程:
1. 在 writech.hk 的分发脚本(`deploy_certs.sh`)中添加新服务器地址
2. 配置 writech.hk 到新服务器的 SSH 免密登录(`ssh-copy-id`
3. 手动触发一次分发或等待下次 cron 自动续期时同步
4. 新服务器 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 应用服务器动态管理
应用服务器及其上部署的应用会按需增减,平台设计须适应此动态变化:
#### 新增服务器流程
1. **资源开通**:在腾讯云/阿里云开通新云服务器实例
2. **基础配置**:安装 Nginx、Docker 等基础环境
3. **接入认证**:配置 Keycloak OIDC 客户端,接入统一登录
4. **证书部署**:在 writech.hk 分发脚本中添加新服务器,同步 SSL 证书
5. **DNS 解析**:按需添加子域名解析记录
6. **应用部署**:部署业务应用容器
7. **Nginx 反代**:配置反向代理和 SSL 终止
8. **注册到 LDAP**:如有新服务角色,在 LDAP 中添加对应服务条目
#### 缩减服务器流程
1. **业务迁移**:将应用和数据迁移至其他服务器
2. **DNS 摘除**:删除或更新相关 DNS 记录
3. **证书脚本清理**:从 `deploy_certs.sh` 中移除该服务器
4. **Keycloak 清理**:删除对应 OIDC 客户端配置
5. **资源释放**:销毁云服务器实例
### 6.2 配置即代码
所有服务器配置、部署脚本、Nginx 配置均纳入 Git 仓库管理,确保:
- 新服务器可通过脚本快速初始化
- 配置变更有版本记录,可回溯可审计
- 服务器增减时只需修改配置文件并执行部署脚本
---
## 七、账户生命周期管理
### 7.1 员工入职 — 开通账户
```plantuml
@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 盘 |
#### 公钥注册流程
1. 员工本地执行 `ssh-keygen -t ed25519 -C "name@writech.cn"` 生成秘钥对
2.`~/.ssh/id_ed25519.pub` 内容通过安全渠道提交给 IT 管理员
3. IT 管理员通过 LDAP 管理工具将公钥写入该用户条目
4. 写入后,员工即可通过 SSH 秘钥访问 Git、服务器等全部 SSH 类服务
5. 员工登录 Keycloak 自助页面,注册 WebAuthn 设备用于 Web 类服务
6. 员工在 Keycloak 账户设置中关联微信账号(扫码绑定 OpenID),作为移动端登录的替代方式
### 7.3 员工电脑更换 — 秘钥迁移
#### 推荐方案:生成新秘钥
1. 在新电脑上**重新生成**新的 SSH 秘钥对
2. 将新公钥提交给 IT 管理员
3. IT 管理员在 LDAP 中**追加**新公钥(保留旧公钥,过渡期并存)
4. 员工在新电脑验证全部系统可正常访问
5. IT 管理员**删除**旧公钥
6. 在 Keycloak 中注册新电脑的 WebAuthn 设备
> **注意**:微信扫码登录绑定与电脑无关(绑定在手机微信上),更换电脑不影响微信扫码登录。
#### 紧急方案:迁移旧秘钥
若需立即使用且来不及走流程:
1. 通过加密 U 盘将旧电脑 `~/.ssh/` 目录中的私钥文件拷贝到新电脑
2. 确认拷贝后,**立即安全擦除** U 盘中的秘钥文件
3. 在新电脑验证连接正常
4. **建议后续仍重新生成秘钥**并替换,降低私钥泄露风险
### 7.4 员工离职 — 权限回收
离职权限回收必须在**员工最后工作日当天完成**,流程如下:
```plantuml
@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
---
## 八、系统部署拓扑
```plantuml
@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 周 |
| **第四阶段:运营优化** | 弹性扩缩自动化脚本开发 | 按需 |
| **第四阶段** | 全系统安全审计与渗透测试 | 按需 |