# certs-example

**Repository Path**: lh1985/certs-example

## Basic Information

- **Project Name**: certs-example
- **Description**: 内网 自签名证书制作
- **Primary Language**: Shell
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 内网 TLS / 自签名证书部署规范

本项目提供内网环境下 HTTPS / WSS / WebRTC / Electron 的完整证书部署方案。通过自建 Root CA + Server 证书的方式，最大程度降低客户端异常率，确保各平台应用的稳定运行。

## 项目特点

- **安全可靠**：采用 Root CA + Server 证书的两级结构，符合生产级安全标准
- **全面覆盖**：支持 Linux、Windows、macOS、信创OS等主流操作系统
- **场景丰富**：适用于 WebRTC、mediasoup、Electron、Node.js、Java 等多种技术栈
- **文档完善**：提供从证书生成到客户端部署的完整指南
- **开箱即用**：提供交互式证书生成脚本，简化部署流程

## 项目结构

```
.
├── README.md                    # 项目总览（本文件）
├── generate-certs.sh            # 证书生成脚本（交互式）
├── server.conf.example          # 服务器证书配置模板
├── LICENSE                      # 许可证文件
├── .gitignore                   # Git 忽略配置
└── docs/                        # 详细文档目录
    ├── README.md                # 文档总入口
    ├── ubuntu22.04-dependencies.md  # Ubuntu 环境依赖指南
    ├── cert/                    # 证书体系文档
    │   ├── 00-quick-start.md    # 快速开始指南
    │   ├── 01-cert-overview.md  # 证书体系设计说明
    │   ├── 02-cert-generate.md  # 证书生成详细指南
    │   ├── 03-cert-deploy-intranet.md  # 内网服务器部署规范
    │   ├── 04-cert-client-trust.md     # 客户端信任配置指南
    │   ├── 05-domain-certificate.md     # 域名证书生成指南（如 webrtc.local）
    │   └── 06-intranet-dns-config.md    # 内网域名解析配置指南
    ├── webrtc/                  # WebRTC 场景专用文档
    │   ├── webrtc-mediasoup-cert.md    # WebRTC/mediasoup 证书规范
    │   └── mediasoup-nginx-example.md  # mediasoup + nginx 部署示例
    ├── electron/                # Electron 客户端文档
    │   └── electron-cert-whitelist.md  # Electron 证书信任方案
    └── xinchuang/               # 信创环境适配文档
        └── xinchuang-os-cert-guide.md  # 国产操作系统证书配置
    └── examples/                # 使用示例
        └── webrtc-local-example.md     # webrtc.local 域名证书示例
```

## 快速开始

### 一键配置域名（可选）⭐

如果使用域名（如 `webrtc.local`），可以使用自动化脚本快速配置：

```bash
# Linux/macOS/WSL
chmod +x setup-dns.sh
./setup-dns.sh

# 输入域名: webrtc.local
# 输入 IP: 192.168.1.61
# 脚本自动完成配置和测试 ✅
```

**Windows**（需要管理员权限）：

```cmd
# 方式一：双击运行批处理文件（推荐⭐，最简单）
快速配置域名.bat
# 或
setup-dns.bat

# 方式二：使用 PowerShell
# 1. 以管理员身份运行 PowerShell
# 2. 切换到脚本目录: cd D:\code2026\certs-example
# 3. 执行: .\setup-dns.ps1
#    注意：必须使用 .\ 前缀
# 4. 如果提示执行策略限制，先执行:
#    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

> 💡 **Windows 用户提示**: 如果遇到"无法识别"错误，请使用 `.\setup-dns.ps1`（注意 `.\` 前缀）或直接使用 `setup-dns.bat`。详细说明请参考 [SETUP-DNS-README.md](./SETUP-DNS-README.md)

**脚本功能**：
- ✅ 交互式输入域名和 IP
- ✅ 自动配置 hosts 文件
- ✅ 自动刷新 DNS 缓存
- ✅ 自动测试域名解析
- ✅ 支持更新已存在的配置

### 环境要求

- 操作系统：Ubuntu 22.04 桌面版（推荐）或其他 Linux 发行版
- 依赖工具：OpenSSL 3.0.x 或更高版本

### 1. 检查依赖

```bash
# 方式一：使用脚本自动检查
./generate-certs.sh

# 方式二：手动检查
openssl version
```

### 2. 生成证书

```bash
# 赋予执行权限
chmod +x generate-certs.sh

# 运行交互式生成脚本
./generate-certs.sh

# 脚本会提示：
# 1. 选择证书类型：IP 地址 或 域名（如 webrtc.local）
# 2. 输入 IP 地址或域名
# 3. 可选：添加 DNS 域名或 IP 地址到证书
# - 确认配置
```

### 3. 服务器配置

将生成的证书文件部署到服务器：

| 文件 | 说明 | 权限要求 |
|------|------|----------|
| `server.crt` | 服务器证书 | 所有用户可读 |
| `server.key` | 服务器私钥 | 仅所有者可读 |
| `rootCA.crt` | 根证书（客户端需安装） | - |

### 4. 客户端信任配置

将 `rootCA.crt` 安装到客户端系统信任库：

**Linux (Ubuntu)**
```bash
sudo cp rootCA.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

**Windows**
双击 `rootCA.crt`，选择"安装证书"→"受信任的根证书颁发机构"

**Java**
```bash
keytool -importcert -alias InternalRootCA -keystore $JAVA_HOME/lib/security/cacerts -file rootCA.crt
```

## 核心功能

### 证书生成工具

`generate-certs.sh` 提供完整的证书生成能力：

- 自动生成 Root CA（4096 位 RSA）
- 自动生成服务器证书（含 SAN 配置）
- 交互式配置 IP 和域名
- 自动验证证书有效性
- 生成配置文件模板

### 文档体系

| 文档 | 内容 |
|------|------|
| 证书体系说明 | 介绍为何使用 Root CA + Server 证书结构 |
| 证书生成指南 | 手动生成流程及常见问题处理 |
| 内网部署规范 | 服务器配置、权限设置、监控告警 |
| 客户端信任指南 | 各平台系统级和应用级信任配置 |
| WebRTC 规范 | DTLS 证书要求、mediasoup 集成 |
| Electron 方案 | 白名单机制、session 证书配置 |
| 信创环境适配 | 统信UOS、麒麟OS等国产系统配置 |

## 适用场景

- WebRTC 视频会议和屏幕共享系统
- mediasoup / SFU 内网部署
- Electron 桌面客户端应用
- Node.js / Java 后端 HTTPS 服务
- 企业内网和专网环境
- 国产操作系统信创环境

## 核心原则

✅ **必须遵守**

- 使用 Root CA 签发服务器证书，禁止直接自签 server.crt
- 证书必须配置 SAN（支持 IP 和 DNS）
- HTTPS / WSS / DTLS 使用统一证书体系
- 客户端仅信任 Root CA

❌ **禁止使用**

- 长期使用 `NODE_TLS_REJECT_UNAUTHORIZED=0`
- 生产环境关闭 TLS 校验
- 直接使用 server.crt 作为信任锚点

## 文档导航

| 主题 | 文档链接 |
|------|----------|
| 快速开始 | [docs/cert/00-quick-start.md](./docs/cert/00-quick-start.md) |
| 证书体系 | [docs/cert/01-cert-overview.md](./docs/cert/01-cert-overview.md) |
| 生成指南 | [docs/cert/02-cert-generate.md](./docs/cert/02-cert-generate.md) |
| 服务器部署 | [docs/cert/03-cert-deploy-intranet.md](./docs/cert/03-cert-deploy-intranet.md) |
| 客户端信任 | [docs/cert/04-cert-client-trust.md](./docs/cert/04-cert-client-trust.md) |
| WebRTC 场景 | [docs/webrtc/webrtc-mediasoup-cert.md](./docs/webrtc/webrtc-mediasoup-cert.md) |
| Electron 方案 | [docs/electron/electron-cert-whitelist.md](./docs/electron/electron-cert-whitelist.md) |
| 信创环境 | [docs/xinchuang/xinchuang-os-cert-guide.md](./docs/xinchuang/xinchuang-os-cert-guide.md) |

## 技术支持

如有问题或建议，欢迎提交 Issue 或 Pull Request。

## 许可证

本项目基于 MIT 许可证开源。

## 注意事项

本项目提供的证书方案适用于内网/私有环境，不适用于公网生产环境。公网环境请使用受信任的 CA 签发的证书。