# 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 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 认证架构

```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 API（dns_ali），.cn 域名通过腾讯云 DNSPod API（dns_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 周 |
| **第四阶段：运营优化** | 弹性扩缩自动化脚本开发 | 按需 |
| **第四阶段** | 全系统安全审计与渗透测试 | 按需 |