ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sync: add ses and networking notes

Browse Source
This commit is contained in:
weishen
2026-04-24 20:38:20 +08:00
parent e4f6f463cb
commit 7903d703b9
12 changed files with 925 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
Project/fonrey/DATA_MODEL/DATA_MODEL_PUBLIC.md
View File

@@ -4,7 +4,7 @@
> **版本**: v1.0 > **版本**: v1.0
> **日期**: 2026-04-24 > **日期**: 2026-04-24
> **权威源**: 本文件是 `public` schema 所有表的唯一权威定义 > **权威源**: 本文件是 `public` schema 所有表的唯一权威定义
> **设计依据**: 系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`） > **设计依据**: 系统管理模块 PRD（`PRD/系统管理/系统管理模块PRD.md`）；客户端发布管理模块 PRD（`PRD/发布管理/客户端发布管理模块PRD.md`）
> **索引文档**: [`DATA_MODEL.md §三`](./DATA_MODEL.md)（仅保留摘要索引，开发以本文件为准） > **索引文档**: [`DATA_MODEL.md §三`](./DATA_MODEL.md)（仅保留摘要索引，开发以本文件为准）
--- ---
@@ -31,7 +31,8 @@ PostgreSQL Instance
│ ├── backup_records 备份记录 │ ├── backup_records 备份记录
│ ├── export_tasks 数据导出 │ ├── export_tasks 数据导出
│ ├── system_versions 版本历史 │ ├── system_versions 版本历史
│ └── upgrade_events 升级记录 │ ├── upgrade_events 升级记录
│ └── client_releases 客户端版本发布
│ │
├── tenant_abc schema（租户业务层，见各子文档） ├── tenant_abc schema（租户业务层，见各子文档）
└── tenant_xyz schema └── tenant_xyz schema
@@ -54,6 +55,7 @@ PostgreSQL Instance
| `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump） | §2.4 | | `public.export_tasks` | 数据导出异步任务（CSV/JSON/SQL Dump） | §2.4 |
| `public.system_versions` | 平台版本历史，唯一 current 约束 | §2.5 | | `public.system_versions` | 平台版本历史，唯一 current 约束 | §2.5 |
| `public.upgrade_events` | 升级/回滚事件，含灰度租户维度进度快照 | §2.5 | | `public.upgrade_events` | 升级/回滚事件，含灰度租户维度进度快照 | §2.5 |
| `public.client_releases` | Windows 客户端发布版本，含安装包 URL、SHA256、强制更新标记 | §2.6 |
--- ---
@@ -376,6 +378,87 @@ CREATE TABLE public.upgrade_events (
CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_at DESC); CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_at DESC);
``` ```
### 2.6 客户端发布管理
```sql
-- ────────────────────────────────────────────────────────────
-- 6. 客户端发布管理
-- ────────────────────────────────────────────────────────────
-- 设计依据: 客户端发布管理模块 PRD §5.3
-- 说明: 本表属于 shared_apps（public schema），所有租户共享同一套客户端版本，
-- 不做多租户隔离。
-- 客户端版本发布表
CREATE TABLE public.client_releases (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-- 版本标识
version VARCHAR(20) UNIQUE NOT NULL,
-- SemVer 格式，如 '1.2.3'；由应用层校验格式，数据库层仅保证唯一性
platform VARCHAR(20) NOT NULL DEFAULT 'win32'
CHECK (platform IN ('win32')),
-- 当前仅支持 Windows；后续支持 darwin / linux 时扩展 CHECK
arch VARCHAR(10) NOT NULL DEFAULT 'x64'
CHECK (arch IN ('x64', 'arm64')),
-- 版本类型与状态
release_type VARCHAR(10) NOT NULL DEFAULT 'normal'
CHECK (release_type IN ('normal', 'force')),
-- normal = 普通更新，提示但可延后；force = 强制升级，不可跳过
status VARCHAR(10) NOT NULL DEFAULT 'draft'
CHECK (status IN ('draft', 'published', 'archived')),
-- draft = 草稿，不对外生效；published = 已发布，客户端可感知；archived = 已下线
-- 兼容性约束
min_required_version VARCHAR(20),
-- 低于该版本的客户端将被强制要求升级，NULL = 无最低版本限制
-- 由应用层在查询时比较 SemVer，数据库层不做运算
-- 安装包（EXE）
download_url TEXT NOT NULL,
-- Cloudflare R2 公开 URL，格式：
-- https://download.fonrey.com/releases/v{version}/fonrey-setup-{version}-win.exe
checksum_sha256 VARCHAR(64) NOT NULL,
-- 安装包 SHA256 十六进制字符串（64 位），客户端下载完成后校验
file_size_bytes BIGINT,
-- 安装包字节大小，用于前端展示下载大小
-- 便携版（ZIP，可选）
portable_url TEXT,
-- 无需安装的 ZIP 版本，供无管理员权限的企业环境使用
portable_checksum_sha256 VARCHAR(64),
-- 更新内容
release_notes TEXT NOT NULL,
-- 对外展示的更新日志，Markdown 格式，最多 2000 字
internal_notes TEXT,
-- 内部技术说明，不对外展示
-- 统计
download_count INTEGER NOT NULL DEFAULT 0,
-- 该版本安装包被下载次数，由应用层在每次下载时原子递增
-- 时间与操作人
published_at TIMESTAMPTZ,
-- 首次设为 published 时记录，后续状态变更不更新此字段
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
created_by UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL,
published_by UUID REFERENCES public.platform_admins(id) ON DELETE SET NULL
);
-- 只允许一条 published 记录（同平台+架构下的当前生效版本）
CREATE UNIQUE INDEX idx_client_releases_published
ON public.client_releases(platform, arch)
WHERE status = 'published';
-- 快速查找草稿/已发布版本（管理后台列表查询）
CREATE INDEX idx_client_releases_status ON public.client_releases(status, created_at DESC);
-- 按版本号快速定位（客户端更新检测时传入 current_version 查询）
CREATE INDEX idx_client_releases_version ON public.client_releases(version);
```
--- ---
## 三、关键约束与禁止操作 ## 三、关键约束与禁止操作
@@ -391,6 +474,9 @@ CREATE INDEX idx_upgrade_events_status ON public.upgrade_events(status, created_
| `platform_admins` 与 `staff` 完全独立 | 不共享表、不共享 auth 系统 | | `platform_admins` 与 `staff` 完全独立 | 不共享表、不共享 auth 系统 |
| MFA 强制 | `platform_admins.mfa_enabled` 在首次 TOTP 确认后才变 TRUE；登录流必须检查 | | MFA 强制 | `platform_admins.mfa_enabled` 在首次 TOTP 确认后才变 TRUE；登录流必须检查 |
| `admin_sessions` 30 分钟滚动超时 | 应用层每次活跃请求更新 `expires_at = NOW() + 30min` | | `admin_sessions` 30 分钟滚动超时 | 应用层每次活跃请求更新 `expires_at = NOW() + 30min` |
| `client_releases` 唯一 published | `idx_client_releases_published` 部分唯一索引保证同平台+架构下只有一条 `status='published'` |
| `client_releases` 不可跨租户隔离 | 本表属于 public schema，所有租户共享；禁止在租户 schema 中创建副本 |
| `client_releases.download_count` 原子递增 | 必须使用 `UPDATE ... SET download_count = download_count + 1`，禁止先读后写 |
--- ---
@@ -468,6 +554,27 @@ FROM public.backup_records br
JOIN public.tenants t ON t.id = br.tenant_id JOIN public.tenants t ON t.id = br.tenant_id
WHERE br.status IN ('pending', 'in_progress') WHERE br.status IN ('pending', 'in_progress')
ORDER BY br.created_at DESC; ORDER BY br.created_at DESC;
-- 客户端更新检测：查询当前生效版本（platform=win32, arch=x64）
SELECT version, release_type, download_url, portable_url,
checksum_sha256, file_size_bytes, release_notes, published_at
FROM public.client_releases
WHERE platform = 'win32'
AND arch = 'x64'
AND status = 'published'
LIMIT 1;
-- 客户端版本管理列表（管理后台，含各状态版本）
SELECT version, platform, arch, release_type, status,
download_count, published_at, created_at
FROM public.client_releases
ORDER BY created_at DESC;
-- 统计各版本活跃客户端数（需结合客户端上报心跳表，当前仅记录下载量）
SELECT version, download_count
FROM public.client_releases
WHERE status IN ('published', 'archived')
ORDER BY published_at DESC;
``` ```
### 5.2 禁止查询 ### 5.2 禁止查询
@@ -478,6 +585,8 @@ ORDER BY br.created_at DESC;
| `DELETE FROM public.platform_audit_logs` | append-only 审计表 | | `DELETE FROM public.platform_audit_logs` | append-only 审计表 |
| `UPDATE public.tenants SET schema_name = ...` | schema 名绑定 PG 物理 schema | | `UPDATE public.tenants SET schema_name = ...` | schema 名绑定 PG 物理 schema |
| `UPDATE public.domains SET domain = ...` | 域名路由不可变 | | `UPDATE public.domains SET domain = ...` | 域名路由不可变 |
| `UPDATE public.client_releases SET version = ...` | 版本号创建后不可修改，变更须新建记录 |
| 在租户 schema 中创建 `client_releases` 副本 | 本表属于 public schema，多租户共享，禁止下沉到租户层 |
--- ---
@@ -486,3 +595,4 @@ ORDER BY br.created_at DESC;
| 版本 | 日期 | 变更 | | 版本 | 日期 | 变更 |
|------|------|------| |------|------|------|
| v1.0 | 2026-04-24 | 从 `DATA_MODEL.md §三` 独立拆分；内容等价于 v1.2 DATA_MODEL.md §三 | | v1.0 | 2026-04-24 | 从 `DATA_MODEL.md §三` 独立拆分；内容等价于 v1.2 DATA_MODEL.md §三 |
| v1.1 | 2026-04-24 | 新增 §2.6 `client_releases` 表（客户端发布管理）；同步更新表清单、约束规则、查询模式 |

407
Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md Normal file
View File

@@ -0,0 +1,407 @@
# PRD: 客户端发布管理模块
**状态**: Draft
**作者**: 产品经理
**最后更新**: 2026-04-24（v1.0 初稿）
**版本**: 1.0
**所属系统**: Fonrey 房产经纪管理系统
**关联模块**: 系统管理、权限管理
**干系人**: 工程负责人、运维负责人、系统管理员
---
## 1. 问题陈述
### 背景
Fonrey 房产经纪管理系统当前为纯 Web 应用，依赖用户自行通过浏览器访问。然而在实际部署场景中，经纪公司的终端设备环境高度复杂：
- **浏览器版本参差不齐**：经纪人使用的 Windows 设备可能运行 IE11、旧版 Edge、或未更新的 Chrome，导致 HTMX + Alpine.js 等现代前端技术出现兼容性问题，系统体验碎片化
- **交付和部署门槛高**：IT 能力薄弱的经纪公司无法独立配置浏览器访问方式，URL 记忆成本高，容易访问错误版本
- **版本管理缺失**：后端服务升级后，用户仍可能使用旧版缓存页面操作，导致接口不兼容和功能异常
- **无官方入口**：用户通过私发链接访问系统，存在钓鱼仿冒风险，且无法统一品牌形象
### 目标用户
| 角色 | 使用场景 | 使用频率 |
|------|---------|----------|
| 一线经纪人 | 下载安装客户端、日常登录使用系统、接受自动更新 | 每日 |
| 店长/经理 | 同上 | 每日 |
| 系统管理员 | 发布新版本、管理安装包下载地址、监控客户端版本分布 | 按需 |
| IT 运维人员 | 维护更新服务器、签名证书、构建发布流水线 | 按发布周期 |
### 核心痛点
1. **无法控制用户使用的浏览器环境**，兼容性问题无法从根源解决
2. **升级依赖用户主动刷新浏览器**，后端 API 变更时旧客户端可能造成数据错误
3. **缺乏官方分发渠道**，无法向终端用户传递信任感和版本一致性保障
4. **SaaS 多租户管理系统需要统一、可控的客户端入口**，避免因客户端环境差异导致的支持成本上升
---
## 2. 目标与成功指标
| 目标 | 指标 | 当前基准 | 目标值 | 衡量周期 |
|------|------|---------|--------|---------|
| 消除浏览器兼容性问题 | 因浏览器兼容产生的支持工单数 | 待统计 | 降低 ≥ 90% | 上线后 60 天 |
| 提升版本一致性 | 在线用户中使用最新版本客户端的比例 | 0%（无客户端） | ≥ 95% | 版本发布后 7 天 |
| 降低部署门槛 | 新客户从获取安装包到完成首次登录的时间 | 无基准 | ≤ 10 分钟 | 上线后首批客户反馈 |
| 自动更新成功率 | 客户端自动更新完成率（收到更新通知 → 升级完成） | 无基准 | ≥ 98% | 每次版本发布后 48 小时 |
---
## 3. 非目标（本期不做）
- **不支持 macOS / Linux 客户端**：目标用户群体 99% 使用 Windows，macOS 版本为后续规划
- **不支持移动端 App（iOS / Android）**：移动端为 v2 规划，本期不涉及
- **不开发私有化部署的离线安装方案**：本期聚焦 SaaS 在线版，私有化部署另行规划
- **不包含客户端内置的离线模式**：系统需联网使用，客户端不缓存业务数据供离线访问
- **不包含客户端层面的安全加固（如代码混淆、反逆向）**：本期以功能交付为优先，安全加固列入后续迭代
---
## 4. 用户故事与验收标准
---
### Story 1：经纪人下载并安装客户端
**As** 一线经纪人，**I want** 通过公司提供的网址下载一个安装程序并完成安装，**So that** 我可以立即打开登录界面使用 Fonrey 系统，无需手动配置浏览器。
**验收标准**：
- [ ] 官方下载页面可通过指定 URL 访问，页面展示最新版本号、发布日期及下载按钮
- [ ] 下载产物为单一 `.exe` 安装包（或免安装便携版 `.zip`），文件大小控制在合理范围内
- [ ] 双击安装包后，安装向导步骤不超过 3 步（下一步 → 选择安装路径 → 安装），无需勾选额外组件
- [ ] 安装完成后，桌面自动生成快捷方式（图标为 Fonrey 品牌 Logo）
- [ ] 首次启动后直接显示登录界面，无需用户手动输入任何 URL
- [ ] 安装包经过代码签名，Windows SmartScreen 不弹出"无法识别的应用"警告
- [ ] 安装过程无需管理员权限（支持用户级安装到 `%APPDATA%` 目录），降低企业 IT 审批障碍
---
### Story 2：经纪人使用客户端正常登录并使用系统
**As** 一线经纪人，**I want** 打开客户端后直接访问 Fonrey 系统的完整功能，**So that** 我的日常使用体验与使用 Chrome 浏览器无差异，且不受本机安装的浏览器版本影响。
**验收标准**：
- [ ] 客户端内嵌现代 Chromium 内核（如基于 Electron 或 WebView2），版本不低于 Chromium 100，支持现代 Web 标准（ES2020、CSS Grid、Fetch API 等）
- [ ] HTMX 局部刷新、Alpine.js 状态交互、Tailwind CSS 样式在客户端中渲染效果与 Chrome 最新版一致
- [ ] 支持 Cookie / Session 存储，登录状态在客户端关闭后保留（复用 Django Session 机制）
- [ ] 文件上传（图片、附件）、文件下载（Excel 导出）在客户端中正常工作
- [ ] 客户端窗口支持最大化、最小化、拖拽调整大小，支持多显示器
- [ ] 客户端标题栏显示应用名称和当前版本号（如：`Fonrey 房睿 v1.2.3`）
- [ ] 客户端不显示浏览器默认的地址栏、书签栏、扩展工具栏，保持沉浸式应用体验
---
### Story 3：客户端感知新版本并自动升级
**As** 一线经纪人，**I want** 客户端在有新版本时自动提示并完成升级，**So that** 我无需手动下载安装，始终使用最新版本，不会因版本落后导致功能异常。
**验收标准**：
- [ ] 客户端启动时及运行期间（每隔 4 小时）自动向更新服务器检查最新版本
- [ ] 有新版本时，客户端右下角弹出非阻断式通知："发现新版本 vX.X.X，点击立即更新"，用户可选择"立即更新"或"稍后提醒"
- [ ] 点击"立即更新"后，客户端在后台静默下载更新包，进度条显示下载进度
- [ ] 下载完成后提示用户"更新已就绪，重启客户端完成安装"，用户选择"立即重启"或"下次启动时安装"
- [ ] 重启后，新版本生效，标题栏版本号更新，历史会话自动恢复（用户无需重新登录）
- [ ] 支持强制更新模式：服务端可标记某版本为"强制升级"，客户端不展示"稍后提醒"选项，必须升级后方可继续使用（用于重大 API 兼容性变更场景）
- [ ] 更新失败时（网络中断、磁盘空间不足等），客户端显示错误提示并保持当前版本正常运行，不影响用户当前操作
---
### Story 4：系统管理员发布新版本
**As** 系统管理员，**I want** 通过管理后台上传新版客户端安装包并配置版本信息，**So that** 客户端能感知到更新并引导用户升级。
**验收标准**：
- [ ] 系统管理后台提供"客户端版本管理"页面（位于系统管理模块下）
- [ ] 支持上传 `.exe` 安装包，并填写版本号（遵循 SemVer：`X.Y.Z`）、版本说明（更新日志，支持 Markdown）、发布日期
- [ ] 支持设置版本类型：普通更新 / 强制更新
- [ ] 支持设置版本状态：草稿（不对外生效）/ 已发布 / 已下线
- [ ] 发布后，更新服务器 API 即时返回最新版本信息，客户端下次检测时可感知
- [ ] 支持版本回滚：将指定历史版本重新设为"已发布"，自动将当前版本标记为已下线
- [ ] 支持查看各版本的下载量和活跃客户端版本分布统计
---
### Story 5：管理员监控客户端版本分布
**As** 系统管理员，**I want** 查看当前所有在线客户端的版本分布情况，**So that** 了解升级覆盖率，对仍在使用旧版本的客户端发出提醒或强制升级。
**验收标准**：
- [ ] 客户端版本管理页面展示版本分布统计：各版本在线客户端数量及占比（饼图或条形图）
- [ ] 支持按租户维度查看版本分布（多租户场景下，区分不同经纪公司的版本使用情况）
- [ ] 支持对指定版本范围的用户推送"强制更新"通知（如：将所有低于 v1.5.0 的客户端标记为强制更新）
---
## 5. 功能详细说明
### 5.1 技术架构选型
#### 5.1.1 客户端技术方案
基于 Fonrey 现有技术栈（Django + HTMX + Alpine.js + Tailwind CSS，后端已采用 Docker Compose 部署），客户端本质是一个**内嵌现代 Chromium 内核的原生 Windows 应用外壳（Shell）**，其核心职责是：
1. 提供操作系统级原生窗口（标题栏、任务栏图标、托盘）
2. 内嵌高版本 Chromium 内核加载 Fonrey Web 应用 URL
3. 实现版本检测与自动更新逻辑
4. 处理文件下载、本地存储等 OS 级能力
**推荐方案：Electron（主选）**
| 维度 | Electron | Tauri | WebView2 封装 |
|------|---------|-------|--------------|
| 内核控制 | ✅ 捆绑 Chromium，100% 可控 | ❌ 依赖系统 WebView，版本不可控 | ⚠️ 依赖 Windows 内置 WebView2 Runtime |
| 包体大小 | ~150MB（可接受） | ~5MB | ~5MB |
| 生态成熟度 | ✅ 最成熟，社区最大 | ✅ 较新但活跃 | ⚠️ 微软官方但文档偏少 |
| 自动更新支持 | ✅ `electron-updater` 成熟方案 | ✅ 内置更新器 | ⚠️ 需自行实现 |
| 跨平台 | ✅ Win/Mac/Linux | ✅ | ❌ 仅 Windows |
| 团队技术匹配 | ✅ 主进程用 Node.js，渲染层纯 Web | ⚠️ 主进程需 Rust | ✅ 主进程用 C# |
| **推荐度** | **✅ 主选** | 次选 | 备选 |
**选型决策**：采用 **Electron + electron-updater**。理由：
- 内嵌 Chromium 内核是本需求的核心约束，Electron 是唯一能 100% 保证内核版本可控的主流方案
- `electron-updater` 配合 GitHub Releases 或自建 S3/R2 存储可实现完整的版本管理与自动更新流程，开发成本最低
- 渲染层完全复用 Fonrey 现有 Web 技术栈，无需新增前端框架学习成本
- 团队具备 JavaScript/Node.js 能力，主进程开发门槛可控
**技术决策**：客户端不内置任何业务逻辑，所有业务功能由服务端 Fonrey Web 应用提供。客户端仅负责加载 Web 应用、更新管理和 OS 级能力（窗口、托盘、文件下载路径）。
---
#### 5.1.2 更新服务架构
更新机制采用**差量检测 + 全量包下载**模式：
```
客户端启动 / 定时检测（每4小时）
│
▼
GET /api/client/updates/latest?platform=win32&arch=x64&current_version=1.2.0
│
▼
更新服务器（Fonrey 后端 Django API）
返回：{ latest_version, download_url, release_notes, force_update, checksum }
│
├── 无更新 → 继续正常运行
│
└── 有更新 → 弹出通知
│
├── 用户点击"立即更新" → 后台下载 .exe / NSIS 更新包
│ │
│ └── 下载完成 → 校验 SHA256 → 提示重启安装
│
└── 用户选择"稍后" → 下次启动再提示
```
**更新包存储**：上传至 Cloudflare R2（与现有对象存储一致），通过 Cloudflare CDN 加速下载，全国用户均可获得稳定下载速度。
**版本 API 端点**（新增至 Django 后端）：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/client/updates/latest/` | GET | 客户端查询最新版本，返回版本信息和下载 URL |
| `/api/client/updates/` | GET | 管理端查询版本列表（需认证） |
| `/api/client/updates/` | POST | 管理端发布新版本（需管理员权限） |
| `/api/client/updates/<id>/` | PATCH | 管理端修改版本状态（发布/下线/强制） |
---
#### 5.1.3 安装包签名与分发
**代码签名**：
- 使用 EV 代码签名证书（推荐购买 DigiCert 或 Sectigo EV 证书）
- 通过 `electron-builder` 在 CI/CD 构建时自动签名
- 签名后安装包经 Windows SmartScreen 审核，用户安装时不触发安全警告
**安装包分发**：
- 官方下载页：独立 HTML 页面托管于 Cloudflare Pages 或 Nginx 静态站
- 页面展示：最新版本号 + 发布日期 + 更新日志 + 下载按钮
- 下载 URL 格式：`https://download.fonrey.com/releases/v1.2.3/fonrey-setup-1.2.3-win.exe`
- 同时提供便携版（Portable）：`fonrey-portable-1.2.3-win.zip`，供无安装权限的企业环境使用
---
### 5.2 客户端功能规格
#### 5.2.1 主窗口
| 属性 | 规格 |
|------|------|
| 默认窗口尺寸 | 1280 × 800（最小：1024 × 600） |
| 标题栏 | 显示 `Fonrey 房睿 v{version}`，含原生最小化/最大化/关闭按钮 |
| 内嵌 URL | 启动时加载 `https://{tenant}.fonrey.com`（或私有化部署地址，可配置） |
| 地址栏 | 不显示（沉浸式应用模式） |
| 右键菜单 | 仅保留"复制"/"粘贴"/"检查元素（仅开发模式）"，移除"查看源代码"等浏览器默认项 |
| 外部链接 | 点击 `target="_blank"` 链接时，在系统默认浏览器中打开，不在客户端内新窗口打开 |
#### 5.2.2 系统托盘
| 功能 | 说明 |
|------|------|
| 托盘图标 | Fonrey Logo，鼠标悬停显示 `Fonrey 房睿 - 已连接` / `- 离线` |
| 右键菜单 | 打开主窗口 / 检查更新 / 关于 / 退出 |
| 最小化行为 | 点击关闭按钮时最小化至托盘（不退出程序），用户通过托盘图标恢复窗口 |
#### 5.2.3 网络状态感知
| 状态 | 客户端行为 |
|------|-----------|
| 正常联网 | 加载 Fonrey Web 应用，状态栏显示"已连接" |
| 网络断开 | 显示全屏提示页："网络连接已断开，请检查您的网络后重试"，提供"重新连接"按钮 |
| 服务器维护 | 服务器返回 503 时，展示维护提示页（内容由服务端控制） |
#### 5.2.4 文件下载处理
- Excel 导出等文件下载触发时，客户端调用系统原生"另存为"对话框，用户选择保存路径
- 下载完成后，状态栏显示"下载完成，点击打开"提示，点击可直接打开文件
---
### 5.3 版本管理后台（系统管理模块新增页面）
**页面路径**：系统管理 → 客户端发布管理
#### 5.3.1 版本列表
| 列 | 说明 |
|----|------|
| 版本号 | SemVer 格式，如 `v1.2.3` |
| 版本类型 | 普通更新 / 强制更新（红色标签） |
| 状态 | 草稿 / 已发布（绿色）/ 已下线（灰色） |
| 发布时间 | 版本设为已发布的时间 |
| 下载量 | 该版本安装包被下载次数 |
| 操作 | 发布 / 下线 / 编辑 / 复制下载链接 |
#### 5.3.2 新增/编辑版本表单
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| 版本号 | 文本输入 | 是 | 格式：`X.Y.Z`，自动校验 SemVer 格式 |
| 版本类型 | 单选 | 是 | 普通更新 / 强制更新 |
| 最低兼容版本 | 文本输入 | 否 | 低于该版本的客户端将被强制更新（如填写 `1.0.0`，则低于此版本的客户端强制升级） |
| 安装包（EXE） | 文件上传 | 是 | 上传至 Cloudflare R2，最大 500MB |
| 便携版（ZIP） | 文件上传 | 否 | 同上 |
| SHA256 校验值 | 文本输入（自动填充） | 是 | 上传后系统自动计算并填充，用于客户端下载完成后校验完整性 |
| 更新日志 | Markdown 文本区域 | 是 | 展示给用户看的版本说明，最多 2000 字 |
| 发布说明（内部） | 文本区域 | 否 | 仅内部查看的技术说明，不对外展示 |
| 状态 | 单选 | 是 | 草稿 / 立即发布 |
#### 5.3.3 版本分布统计
| 图表 | 说明 |
|------|------|
| 版本分布饼图 | 按客户端版本号统计当前活跃用户数量及占比 |
| 升级进度趋势图 | 新版本发布后，各天累计升级完成的用户比例（折线图） |
| 租户版本明细 | 按租户（经纪公司）展示其员工的客户端版本分布 |
---
### 5.4 更新 API 规格
#### GET `/api/client/updates/latest/`
**请求参数（Query String）**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `platform` | string | 是 | 平台标识，如 `win32` |
| `arch` | string | 是 | CPU 架构，如 `x64` / `arm64` |
| `current_version` | string | 是 | 客户端当前版本号，如 `1.2.0` |
**响应示例（有新版本）**：
```json
{
"has_update": true,
"latest_version": "1.3.0",
"force_update": false,
"download_url": "https://download.fonrey.com/releases/v1.3.0/fonrey-setup-1.3.0-win.exe",
"portable_url": "https://download.fonrey.com/releases/v1.3.0/fonrey-portable-1.3.0-win.zip",
"checksum_sha256": "a1b2c3d4...",
"release_notes": "## v1.3.0 更新内容\n- 新增客源智能配房功能\n- 修复房源列表筛选条件保存异常",
"release_date": "2026-05-01"
}
```
**响应示例（已是最新）**：
```json
{
"has_update": false,
"latest_version": "1.3.0"
}
```
---
## 6. 技术实现注意事项
### 6.1 依赖关系
| 依赖项 | 说明 | 负责方 | 风险等级 |
|--------|------|--------|---------|
| Electron 框架 | 客户端技术基础，需评估 License（MIT，商业可用） | 前端/客户端工程师 | 低 |
| EV 代码签名证书 | 需提前申请，EV 证书审核周期 1-2 周 | IT/运维 | 中（需提前排期） |
| Cloudflare R2 存储桶 | 存放安装包，利用现有账号新增 bucket | 运维 | 低 |
| `electron-updater` | 自动更新库，需配合更新 API 端点实现 | 客户端工程师 | 低 |
| Django 更新 API | 新增 `/api/client/updates/` 相关接口 | 后端工程师 | 低 |
| CI/CD 构建流水线 | 自动构建、签名、上传安装包 | 运维/DevOps | 中 |
### 6.2 已知风险
| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|---------|
| EV 证书申请延迟 | 中 | 高（无签名包无法正常分发） | MVP 阶段可使用普通 OV 证书临时过渡，但需向用户说明安全警告原因 |
| Electron 包体过大导致下载放弃 | 低 | 中 | 使用 `electron-builder` 的 `asar` 压缩 + 分片下载；首包控制在 150MB 以内 |
| 企业网络拦截 CDN 下载 | 中 | 中 | 提供备用下载 URL（直连服务器），支持客户手动下载后本地安装 |
| 自动更新期间用户强制关闭 | 低 | 低 | 更新包下载完成后才替换原文件，下载中断不影响现有版本正常运行 |
| 多租户场景下 URL 配置问题 | 低 | 高 | 客户端启动时加载的 URL 通过配置文件指定，支持定制化部署；SaaS 版统一指向主域名 |
### 6.3 开放问题（开发启动前必须解决）
- [ ] **租户 URL 如何分发到客户端？** 选项 A：客户端硬编码主域名，由服务端重定向到租户子域（`fonrey.com` → `{tenant}.fonrey.com`）；选项 B：安装包内置配置文件，由销售/运维在分发给客户前填写租户子域。——**Owner**: 产品 + 工程 **Deadline**: 开发启动前
- [ ] **代码签名证书采购主体和预算是否确认？** — **Owner**: IT 负责人 **Deadline**: 立项后 1 周
- [ ] **CI/CD 平台选型是否确定？**（GitHub Actions / Jenkins / 其他）— **Owner**: 运维负责人 **Deadline**: 开发启动前
- [ ] **便携版（Portable ZIP）是否纳入 v1 范围？** 便携版可解决企业无安装权限场景，但增加测试成本。— **Owner**: PM **Deadline**: 立项后 1 周
---
## 7. 发布计划
| 阶段 | 时间 | 受众 | 成功门槛 |
|------|------|------|---------|
| 内部 Alpha | 开发完成后 1 周 | 内部团队 + 1 家种子客户 | 核心流程无 P0 Bug，自动更新机制验证通过 |
| 封闭 Beta | Alpha + 2 周 | 3-5 家头部客户 | 安装成功率 ≥ 95%，自动更新成功率 ≥ 95%，无 P0/P1 Bug |
| 正式发布（GA） | Beta + 1 周 | 全部客户 | Beta 阶段目标达成 |
**回滚标准**：若正式发布后 24 小时内出现以下情况，立即下线该版本并恢复上一稳定版本为"已发布"：
- 自动更新失败率 > 5%
- 客户端白屏/崩溃率 > 2%
- 收到 P0 级安全漏洞报告
---
## 8. 附录
### 8.1 竞品参考
| 产品 | 客户端方案 | 更新机制 |
|------|-----------|---------|
| 企业微信 | Electron + 自研内核 | 强制更新，启动时自动下载 |
| 飞书 | Electron | 后台静默更新，重启生效 |
| 钉钉 | Electron | 同上 |
> 房产经纪行业的竞品（如房客多、云客优）均采用 Electron 方案，验证了技术路线的合理性。
### 8.2 术语表
| 术语 | 定义 |
|------|------|
| SemVer | 语义化版本控制（Semantic Versioning）：`主版本号.次版本号.补丁号`，如 `1.2.3` |
| Electron | 由 GitHub 开发的开源框架，允许使用 Web 技术（HTML/CSS/JS）构建跨平台桌面应用，内嵌 Chromium 和 Node.js |
| electron-updater | Electron 生态中成熟的自动更新库，支持增量更新和全量更新 |
| EV 证书 | Extended Validation 代码签名证书，由 CA 机构颁发，可消除 Windows SmartScreen 安全警告 |
| SHA256 | 安全散列算法，用于验证下载文件的完整性，防止篡改或下载损坏 |
| Portable | 便携版，无需安装，解压即用，适合无管理员权限的企业环境 |

71
Project/fonrey/TECH_STACK/TECH_STACK.md
View File

@@ -82,5 +82,74 @@ fonrey/
## 7. 外部服务 (External Services) ## 7. 外部服务 (External Services)
- **监控**：Sentry (已配置用于错误追踪) 。 - **监控**：Sentry (已配置用于错误追踪) 。
- **对象存储**：Cloudflare R2 (用于房源/客源图片与附件) 。 - **对象存储**：Cloudflare R2 (用于房源/客源图片与附件；同时用于客户端安装包存储与分发) 。
- **地图服务**：待规划 (本期不涉及底层地图建设) 。 - **地图服务**：待规划 (本期不涉及底层地图建设) 。
---
## 8. 客户端发布技术栈 (Desktop Client Stack)
> 本节对应 PRD：`Project/fonrey/PRD/发布管理/客户端发布管理模块PRD.md`
> 所有决策均已在 PRD 中完成选型论证，此处为最终结论，直接执行。
### 8.1 客户端框架
- **框架**：[Electron](https://www.electronjs.org/)（当前稳定版）
- **内核**：Electron 捆绑的 Chromium（版本随 Electron 版本固定，不依赖系统浏览器）
- **主进程语言**：Node.js（JavaScript / TypeScript）
- **渲染层**：直接加载 Fonrey Web 应用 URL，100% 复用现有 HTMX + Alpine.js + Tailwind CSS 技术栈，**渲染层不新增任何框架**
### 8.2 自动更新
- **更新库**：`electron-updater`（`electron-builder` 生态，成熟方案）
- **更新包存储**：Cloudflare R2（复用现有存储账号，新增 `releases` bucket）
- **更新包分发**：Cloudflare CDN 加速（复用现有 CDN 配置）
- **更新检测端点**：Django 后端新增 `/api/client/updates/latest/`（GET，公开接口，无需登录）
- **检测时机**：客户端启动时 + 每 4 小时轮询一次
- **更新模式**：后台静默下载，下载完成后提示用户重启；服务端可将版本标记为"强制更新"，客户端不可跳过
### 8.3 安装包构建与签名
- **构建工具**：`electron-builder`（输出 NSIS 安装包 `.exe` + 便携版 `.zip`）
- **目标平台**：Windows x64（优先），ARM64 按需支持
- **代码签名**：EV 代码签名证书（DigiCert 或 Sectigo），由 CI/CD 在构建时自动签名，消除 Windows SmartScreen 警告
- **CI/CD**：待确认平台（GitHub Actions / Jenkins），构建流水线负责：编译 → 签名 → 上传 R2 → 调用发布 API
### 8.4 Django 后端新增模块
在现有 `fonrey/apps/` 目录下新增：
```
apps/
└── release/ # 客户端发布管理
├── models.py # ClientRelease（版本号、类型、状态、下载URL、SHA256、更新日志）
├── views.py # 公开更新检测 API + 管理后台 CRUD 视图
├── urls.py
└── admin.py
```
**`ClientRelease` 模型关键字段**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `version` | CharField | SemVer 格式，如 `1.2.3`，唯一索引 |
| `platform` | CharField | 平台标识，如 `win32` |
| `arch` | CharField | CPU 架构，如 `x64` |
| `release_type` | CharField | `normal` / `force`（强制更新） |
| `status` | CharField | `draft` / `published` / `archived` |
| `download_url` | URLField | EXE 安装包 Cloudflare R2 URL |
| `portable_url` | URLField | ZIP 便携版 URL（可选） |
| `checksum_sha256` | CharField | 安装包 SHA256 校验值 |
| `min_required_version` | CharField | 低于此版本的客户端强制升级（可选） |
| `release_notes` | TextField | Markdown 格式更新日志 |
| `published_at` | DateTimeField | 发布时间 |
**`ClientRelease` 属于 `shared_apps`（公共 Schema）**，不属于租户隔离范围，所有租户共享同一套客户端版本。
### 8.5 客户端关键约定
- **❌ Do NOT** 在 Electron 渲染进程中使用 `nodeIntegration: true`，保持 Web 沙箱安全
- **❌ Do NOT** 在客户端内嵌任何业务逻辑或本地数据库，所有业务数据由服务端提供
- **❌ Do NOT** 在客户端内新开多个 `BrowserWindow` 加载内部页面，所有导航在单窗口 SPA 内完成（外部链接除外，需在系统浏览器打开）
- 客户端版本号必须与服务端 `ClientRelease.version` 严格一致，通过 `package.json` 的 `version` 字段统一管理
- 更新包下载完成后，必须校验 SHA256 与服务端返回值一致后才能执行安装，防止下载损坏或中间人攻击

40
wiki/concepts/DKIM-Email-Authentication.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: "DKIM Email Authentication"
type: concept
tags:
- Email
- Security
- AWS
date: 2026-04-14
---
## Definition
DKIM（DomainKeys Identified Mail）是一种电子邮件验证标准，通过在邮件头部添加数字签名来验证邮件确实由声称的域名授权发送，防止邮件被篡改和伪造。
## How DKIM Works
1. **域名所有者**在 DNS 中发布 DKIM 公钥
2. **发送邮件服务器**使用私钥对邮件头和正文生成数字签名
3. **接收服务器**通过 DNS 查询获取公钥，验证签名有效性
4. 签名包含在邮件头的 `DKIM-Signature` 字段中
## DKIM in AWS SES
AWS SES 支持 DKIM 验证：
- SES 自动为域名生成 DKIM 签名密钥
- 域名所有者需要在 DNS 中添加三条 CNAME 记录
- 启用 DKIM 后，SES 自动对所有出站邮件进行签名
## Related Concepts
- [[SPF]]（Sender Policy Framework）：另一种 DNS ベースの邮件验证方法
- [[DMARC]]（Domain-based Message Authentication, Reporting & Conformance）：综合 SPF 和 DKIM 的邮件验证框架
- [[Email-Security]]：邮件安全的整体方法论
## DKIM vs SPF vs DMARC
| 机制 | 验证内容 | 实施难度 |
|------|----------|----------|
| SPF | 验证发送服务器 IP 是否被域名授权 | 低 |
| DKIM | 验证邮件内容未被篡改 | 中 |
| DMARC | 基于 SPF + DKIM 验证 | 中高 |

46
wiki/concepts/SES-Sandbox-Mode.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: "SES Sandbox Mode"
type: concept
tags:
- AWS
- SES
- Email
- Security
date: 2026-04-14
---
## Definition
SES Sandbox Mode 是 AWS SES（Simple Email Service）的默认限制状态，新注册的 SES 账户在此状态下仅能向经过验证的收件人地址发送少量邮件，无法向外部地址自由发信。
## Sandbox Mode Restrictions
- **仅限验证地址**：只能向已在 SES 中验证过的邮箱地址发送邮件
- **发送限额低**：默认每日发送限额为 200 封/天
- **无外部发信能力**：无法向普通外部邮箱地址（gmail.com、outlook.com 等）发送邮件
- **申请审批制**：需通过 AWS Support 工单申请脱离沙箱
## How to Exit Sandbox Mode
1. 在 SES 控制台确认已完成域名验证（已完成 DKIM 配置）
2. 提交 AWS Support 工单申请"生产访问权限"
3. 在工单中说明使用场景和预计发送量
4. AWS 审批通过后，账户升级至生产模式
## Production Mode Capabilities
脱离 Sandbox Mode 后：
- 可向任意外部邮箱地址发送邮件
- 发送限额大幅提升（可申请更高配额）
- 可用于生产环境邮件发送
## Important Notes
- 即使在生产模式下，仍需遵守 AWS SES 发送策略和最佳实践
- 建议申请脱离 Sandbox Mode 后，同步配置 DMARC 策略保护域名声誉
- 持续监控退回率（bounce rate）和投诉率（complaint rate），避免账户被封禁
## Related Concepts
- [[AWS-SES]]：Amazon Simple Email Service
- [[DKIM-Email-Authentication]]：邮件域名验证
- [[Email-Security]]：邮件安全最佳实践

42
wiki/concepts/VPC-Endpoint.md Normal file
View File

@@ -0,0 +1,42 @@
---
title: "VPC Endpoint"
type: concept
tags:
- AWS
- Networking
- Security
date: 2026-04-14
---
## Definition
VPC Endpoint 是 AWS 提供的一项功能，允许在 VPC 内部通过私有 IP 地址安全地访问 AWS 服务，而无需经过公网、互联网网关、NAT 设备或 VPN 连接。
## Two Types
### Interface Endpoint
- 使用 AWS PrivateLink 技术，在 VPC 中作为弹性网络接口（ENI）部署
- 为 AWS 服务（如 S3、DynamoDB、SES SMTP 等）提供私有连接
- 支持通过安全组控制访问
### Gateway Endpoint
- 用于 S3 和 DynamoDB
- 通过路由表中的目标条目将流量路由到 AWS 服务
- 免费使用
## Key Use Cases
- **SES SMTP 集成**：在应用 VPC 中配置 VPC Endpoint，使应用程序可以在不访问公网的情况下通过私有连接与 SES SMTP 服务通信
- **S3 访问**：在私有子网中的 EC2 实例通过 Gateway Endpoint 安全访问 S3，避免流量经公网
- **Secrets Manager 访问**：通过 Interface Endpoint 安全地访问 Secrets Manager，无需公网连接
## Why Use VPC Endpoints
1. **安全**：流量不经过公网，消除互联网暴露面
2. **低延迟**：私有 IP 直连，减少网络跳数
3. **合规**：满足严格的网络隔离和合规要求
4. **成本**：Gateway Endpoint 免费，Interface Endpoint 费用低于 NAT Gateway
## Related Concepts
- [[AWS-PrivateLink]]：VPC Endpoint 背后使用的核心技术
- [[Infrastructure-as-Code]]：Terraform 模块可自动化 VPC Endpoint 的创建

9
wiki/index.md
View File

@@ -4,6 +4,8 @@
- [Overview](overview.md) — living synthesis - [Overview](overview.md) — living synthesis
## Sources ## Sources
- [2026-04-24] [Learning Sessions Cloud Transformation Programme-Deploying RDS via Terraform](sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md)
- [2026-04-24] [Learning Sessions Cloud Transformation Programme-20230808 183322-Meeting Recording](sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md)
- [2026-04-24] [CTP Topic 16 Cross-account Terraform modules](sources/ctp-topic-16-cross-account-terraform-modules.md) - [2026-04-24] [CTP Topic 16 Cross-account Terraform modules](sources/ctp-topic-16-cross-account-terraform-modules.md)
- [2026-04-24] [Learning Sessions ECS Deployment using IAC - 20230808](sources/learning-sessions-ecs-deployment-using-iac-20230808-183322-meeting-recording.md) - [2026-04-24] [Learning Sessions ECS Deployment using IAC - 20230808](sources/learning-sessions-ecs-deployment-using-iac-20230808-183322-meeting-recording.md)
- [2026-04-24] [CTP Topic 48 Terraform vs Terragrunt](sources/ctp-topic-48-terraform-vs-terragrunt.md) - [2026-04-24] [CTP Topic 48 Terraform vs Terragrunt](sources/ctp-topic-48-terraform-vs-terragrunt.md)
@@ -411,9 +413,7 @@
- [2026-04-20] [design-whimsy-injector](sources/design-whimsy-injector.md) — (expected: wiki/sources/design-whimsy-injector.md — source missing) - [2026-04-20] [design-whimsy-injector](sources/design-whimsy-injector.md) — (expected: wiki/sources/design-whimsy-injector.md — source missing)
- [2026-04-20] [design-ux-architect](sources/design-ux-architect.md) — (expected: wiki/sources/design-ux-architect.md — source missing) - [2026-04-20] [design-ux-architect](sources/design-ux-architect.md) — (expected: wiki/sources/design-ux-architect.md — source missing)
- [2026-04-20] [contributing_zh-cn](sources/contributing_zh-cn.md) — (expected: wiki/sources/contributing_zh-cn.md — source missing) - [2026-04-20] [contributing_zh-cn](sources/contributing_zh-cn.md) — (expected: wiki/sources/contributing_zh-cn.md — source missing)
- [2026-04-20] [ctp-topic-12-using-ses-smtp-service-terraform-module](sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md) — (expected: wiki/sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md — source missing) - [2026-04-14] [CTP Topic 12 Using SES SMTP service terraform module](sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md) — Micro Focus 团队通过 Terraform 模块自动化部署 AWS SES SMTP 服务以替代本地 SMTP 网关；Christian + Filos 主讲；VPC 端点私有连接 + IAM/Secrets Manager 凭证管理
- [2026-04-20] [learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform](sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md) — (expected: wiki/sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md — source missing)
- [2026-04-20] [learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi](sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md) — (expected: wiki/sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md — source missing)
- [Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog](sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md) — (expected: wiki/sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md — source missing) - [Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog](sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md) — (expected: wiki/sources/Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog.md — source missing)
- [Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend](sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md) — (expected: wiki/sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md — source missing) - [Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend](sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md) — (expected: wiki/sources/Expose-hermes-agent-as-an-OpenAI-compatible-API-for-any-frontend.md — source missing)
- [zk-steward](sources/zk-steward.md) — (expected: wiki/sources/zk-steward.md — source missing) - [zk-steward](sources/zk-steward.md) — (expected: wiki/sources/zk-steward.md — source missing)
@@ -902,6 +902,7 @@
- [DevOps-Maturity](concepts/DevOps-Maturity.md) - [DevOps-Maturity](concepts/DevOps-Maturity.md)
- [DevOpsCulture](concepts/DevOpsCulture.md) - [DevOpsCulture](concepts/DevOpsCulture.md)
- [DevSecOps](concepts/DevSecOps.md) - [DevSecOps](concepts/DevSecOps.md)
- [DKIM-Email-Authentication](concepts/DKIM-Email-Authentication.md)
- [dm-verity](concepts/dm-verity.md) - [dm-verity](concepts/dm-verity.md)
- [DNS托管](concepts/DNS托管.md) - [DNS托管](concepts/DNS托管.md)
- [Docker-Compose](concepts/Docker-Compose.md) - [Docker-Compose](concepts/Docker-Compose.md)
@@ -1124,6 +1125,7 @@
- [Secrets-Management](concepts/Secrets-Management.md) - [Secrets-Management](concepts/Secrets-Management.md)
- [Security-and-Compliance](concepts/Security-and-Compliance.md) - [Security-and-Compliance](concepts/Security-and-Compliance.md)
- [Self-Education](concepts/Self-Education.md) - [Self-Education](concepts/Self-Education.md)
- [SES-Sandbox-Mode](concepts/SES-Sandbox-Mode.md)
- [Self-Healing-Systems](concepts/Self-Healing-Systems.md) - [Self-Healing-Systems](concepts/Self-Healing-Systems.md)
- [self-hosted-password-manager](concepts/self-hosted-password-manager.md) - [self-hosted-password-manager](concepts/self-hosted-password-manager.md)
- [Self-Improving-Skill](concepts/Self-Improving-Skill.md) - [Self-Improving-Skill](concepts/Self-Improving-Skill.md)
@@ -1203,6 +1205,7 @@
- [VMware-Cloud-on-AWS](concepts/VMware-Cloud-on-AWS.md) - [VMware-Cloud-on-AWS](concepts/VMware-Cloud-on-AWS.md)
- [Voice-Interface](concepts/Voice-Interface.md) - [Voice-Interface](concepts/Voice-Interface.md)
- [Voice-Notification-Channel](concepts/Voice-Notification-Channel.md) - [Voice-Notification-Channel](concepts/Voice-Notification-Channel.md)
- [VPC-Endpoint](concepts/VPC-Endpoint.md)
- [Vulnerability-Scanning](concepts/Vulnerability-Scanning.md) - [Vulnerability-Scanning](concepts/Vulnerability-Scanning.md)
- [Wake-on-LAN](concepts/Wake-on-LAN.md) - [Wake-on-LAN](concepts/Wake-on-LAN.md)
- [Wayland](concepts/Wayland.md) - [Wayland](concepts/Wayland.md)

24
wiki/log.md
View File

@@ -1,3 +1,13 @@
## [2026-05-05] ingest | Learning Sessions Cloud Transformation Programme-20230808 183322-Meeting Recording
- Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md
- Status: ✅ 成功摄入
- Summary: JP 和 Raja M 主讲，CTP/SRE 团队通过 Terraform IaC 实现 ECS 容器化应用自动化部署——基于 Gruntwork 仓库构建 ECS 模块，支持 Docker 容器/EC2 部署；核心功能：自动扩缩容、自动故障恢复、金丝雀部署；Listener 集中管理方式；前置条件：VPC/ELB 安全组/EFS 卷挂载；集成 CloudWatch/Splunk/Grafana/Prometheus。ECS 作为 AWS 原生技术与 AWS 服务深度集成。
- Concepts linked: [[Infrastructure-as-Code]], [[Canary-Deployment]], [[ECS-Module]]
- Entities linked: [[Gruntwork]], [[AWS]], [[Cloud-Transformation-Programme]]
- Source page: wiki/sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md
- Notes: index.md 已替换占位符条目；overview.md 已新增同主题 wikilink；JP 和 Raja M 各出现 1 次，不足独立 Entity 建页阈值，以 wikilink 形式记录于 Source page；无实质性内容冲突，ECS vs EKS 选型差异记录于 Contradictions 节
- Conflicts: 与 [[ctp-topic-64-scaling-out-with-amazon-eks]] 在容器编排选型上的差异——ECS 强调 AWS 原生集成，EKS 强调可移植性，两者适用于不同场景但可互补
## [2026-05-05] ingest | CTP Topic 16 Cross-account Terraform modules ## [2026-05-05] ingest | CTP Topic 16 Cross-account Terraform modules
- Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/ctp-topic-16-cross-account-terraform-modules.md - Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/ctp-topic-16-cross-account-terraform-modules.md
- Status: ✅ 成功摄入 - Status: ✅ 成功摄入
@@ -2595,3 +2605,17 @@
- Key Entities：Shikad Holtzman 仅出现 1 次，以 wikilink 形式记录于 Source page；Amazon Bedrock/Q/SageMaker 在同系列其他来源中提及频次不足独立建 Entity 页阈值 - Key Entities：Shikad Holtzman 仅出现 1 次，以 wikilink 形式记录于 Source page；Amazon Bedrock/Q/SageMaker 在同系列其他来源中提及频次不足独立建 Entity 页阈值
- 同系列来源关联：已建立与 AI/ML 入门（public-cloud-learning-sessions-introduction-to-artificial-intelligence-ai-machin）和无服务器计算（public-cloud-learning-sessions-opentext-serverless-computing-20240903-160139-mee）的 Connections 关系 - 同系列来源关联：已建立与 AI/ML 入门（public-cloud-learning-sessions-introduction-to-artificial-intelligence-ai-machin）和无服务器计算（public-cloud-learning-sessions-opentext-serverless-computing-20240903-160139-mee）的 Connections 关系
- 冲突检测：与 ctp-topic-64-scaling-out-with-amazon-eks 在扩展方式上的差异已记录于 Source page Contradictions（EDA 事件驱动 vs EKS 容器编排，适用于不同场景可互补） - 冲突检测：与 ctp-topic-64-scaling-out-with-amazon-eks 在扩展方式上的差异已记录于 Source page Contradictions（EDA 事件驱动 vs EKS 容器编排，适用于不同场景可互补）
## [2026-05-06] ingest | Learning Sessions Cloud Transformation Programme-Deploying RDS via Terraform
- Source file: Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md
- Status: ✅ 成功摄入
- Summary: Greg（DBRE 团队）讲解通过 Terraform/Terragrunt 在 AWS 部署 RDS——IaC 六大优势（速度/灵活性/一致性/灾难恢复/文档/自动化）；代码即文档；grunt work RDS Service 推荐生产使用（预建 KMS 加密 + CloudWatch 告警），SRE 核心模块功能弱于 grunt work；Terragrunt 保持代码整洁、避免变量重复；Day 2 运维通过 GitHub PR + Atlantis 实现；CloudWatch Dashboard + Alarms 监控告警，注意突发性能实例 CPU credits
- Concepts linked: [[Infrastructure-as-Code]], [[DRY Principle]], [[GitOps]], [[CloudWatch-Alarms]], [[KMS-Encryption]]
- Entities linked: [[Gruntwork]], [[Atlantis]], [[Terraform]], [[Terragrunt]], [[DBRE]], [[CloudWatch]]
- Source page: wiki/sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md
- Notes:
- index.md 已替换 expected placeholder 条目，补充中文摘要
- overview.md 已新增独立段落（置于 CTP Topic 16 后），与 Terragrunt/Terraform/Gruntwork/Atlantis 等相关来源建立知识链路
- DBRE/Greg 提及 1 次，不足 Entity 建页阈值，以 wikilink 形式记录于 Source page
- CloudWatch/KMS 在 wiki 中已存在关联页面，以 wikilink 形式记录无需新建
- 冲突检测：与 ctp-topic-48-terraform-vs-terragrunt 一致（推荐 Terragrunt）；与 ctp-topic-9-ci-cd-with-gruntwork 互补（Gruntwork CI/CD 基础）；与 ctp-topic-16-cross-account-terraform-modules 共享 Terraform 生态，CI/CD 载体不同无冲突

6
wiki/overview.md
View File

@@ -57,10 +57,14 @@ Cloud Transformation Programme (CTP) materials cover AWS landing zones, EKS, Ter
**[[ctp-topic-48-terraform-vs-terragrunt]]**（CTP Topic 48）：Bob（AWS Solutions Architect）对比 Terraform 与 Terragrunt——Terraform（HashiCorp 出品）是云厂商无关的 Golang 应用，通过状态文件将期望状态与实际环境绑定，企业级使用须将状态文件存储在安全可访问位置；Terragrunt 是 Terraform 的轻量封装，贯彻 DRY 原则，通过管理 provider 和 remote_state 块减少跨环境的重复声明。两者命令和语法高度一致（`terraform plan` = `terragrunt plan`），Terragrunt 通过减少硬编码来优化大规模企业部署。辅助工具：Terraform Enterprise（CI 平台 + workspaces）、Gruntwork（预建可定制模块）、Atlantis（Git 集成）、tfsec（静态安全分析）、Terratest（IaC 测试自动化）。属 [[Infrastructure As Code]] 工具选型层，与 [[ctp-topic-3-deploy-and-maintain-infrastructure]]（Terragrunt HCL）和 [[ctp-topic-56-automated-infrastructure-testing]]（Terratest）共同构成 Terraform 生态知识链路。 **[[ctp-topic-48-terraform-vs-terragrunt]]**（CTP Topic 48）：Bob（AWS Solutions Architect）对比 Terraform 与 Terragrunt——Terraform（HashiCorp 出品）是云厂商无关的 Golang 应用，通过状态文件将期望状态与实际环境绑定，企业级使用须将状态文件存储在安全可访问位置；Terragrunt 是 Terraform 的轻量封装，贯彻 DRY 原则，通过管理 provider 和 remote_state 块减少跨环境的重复声明。两者命令和语法高度一致（`terraform plan` = `terragrunt plan`），Terragrunt 通过减少硬编码来优化大规模企业部署。辅助工具：Terraform Enterprise（CI 平台 + workspaces）、Gruntwork（预建可定制模块）、Atlantis（Git 集成）、tfsec（静态安全分析）、Terratest（IaC 测试自动化）。属 [[Infrastructure As Code]] 工具选型层，与 [[ctp-topic-3-deploy-and-maintain-infrastructure]]（Terragrunt HCL）和 [[ctp-topic-56-automated-infrastructure-testing]]（Terratest）共同构成 Terraform 生态知识链路。
**（本条新增）Learning Sessions ECS Deployment using IAC**（2023-08-08）：JP 和 Raja M 主讲，CTP/SRE 团队通过 Terraform IaC 实现 ECS 容器化应用自动化部署——基于 Gruntwork 仓库构建的 ECS 模块，将 Docker 容器作为逻辑单元，支持 EC2 实例部署；核心功能：自动扩缩容、自动故障恢复、金丝雀部署；通过 Listener 方式集中管理（避免各产品团队重复下载 Gruntwork 代码）；前置条件包括 VPC、ELB 安全组和 EFS 卷挂载；集成 CloudWatch/Splunk/Grafana/Prometheus。ECS 作为 AWS 原生技术与 AWS 服务深度集成，适合追求简单性和紧密集成的场景；属 [[Infrastructure-as-Code]] 在 ECS 场景的实践，与 [[ctp-topic-70-eks-deployment-using-iac]]（EKS IaC 部署）构成容器编排双路径，与 [[ctp-topic-9-ci-cd-with-gruntwork]]（Gruntwork CI/CD）共享 Gruntwork 基础设施基础。与 [[ctp-topic-67-cloud-native-observability-using-opentelemetry]] 在可观测性集成方面关联（ECS 模块集成 CloudWatch/Grafana）。 **（本条新增）Learning Sessions ECS Deployment using IAC**（2023-08-08）：JP 和 Raja M 主讲，CTP/SRE 团队通过 Terraform IaC 实现 ECS 容器化应用自动化部署——基于 Gruntwork 仓库构建的 ECS 模块，将 Docker 容器作为逻辑单元，支持 EC2 实例部署；核心功能：自动扩缩容、自动故障恢复、金丝雀部署；通过 Listener 方式集中管理（避免各产品团队重复下载 Gruntwork 代码）；前置条件包括 VPC、ELB 安全组和 EFS 卷挂载；集成 CloudWatch/Splunk/Grafana/Prometheus。ECS 作为 AWS 原生技术与 AWS 服务深度集成，适合追求简单性和紧密集成的场景；属 [[Infrastructure-as-Code]] 在 ECS 场景的实践，与 [[ctp-topic-70-eks-deployment-using-iac]]（EKS IaC 部署）构成容器编排双路径，与 [[ctp-topic-9-ci-cd-with-gruntwork]]（Gruntwork CI/CD）共享 Gruntwork 基础设施基础。与 [[ctp-topic-67-cloud-native-observability-using-opentelemetry]] 在可观测性集成方面关联（ECS 模块集成 CloudWatch/Grafana）。同主题另一来源：[[learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi]]。
**[[ctp-topic-16-cross-account-terraform-modules]]**（CTP Topic 16）：Fibos 主讲，多账号 AWS 环境中跨账号 Terraform 模块的中心化部署方案——解决原有 Gruntwork 流水线主要针对单账号设计、账号间直接互访存在安全风险（Blast Radius）的问题。核心架构：基于 **Shared Account（共享账号）** 作为中转站，Jenkins 托管于 Shared Account，检测到模块目录中 `cross-account.json` 标记文件后触发 **ECS Deploy Runner**（ECS 上的 Docker 容器）；该 Runner 通过 Assume Role 访问目标账号的两个角色——`TF state bucket accessor`（读取状态文件）和 `cross-account ECS deploy runner role`（执行资源部署）；角色切换逻辑在根目录 `terragrunt.hcl` 中全局配置。实现三大目标：**安全性**（无 Workload 账号间直接信任）、**自动化**（Jenkins 自动识别模块类型）、**可复用性**（模块代码不硬编码特定账号角色）。属 [[Infrastructure-as-Code]] 在多账号场景的进阶实践，与 [[ctp-topic-9-ci-cd-with-gruntwork]]（单账号流水线）构成演进关系，与 [[ctp-topic-32-using-atlantis-cicd-for-infrastructure-deployments]]（Atlantis 跨账号角色）共享 Assume Role 机制但执行载体不同（ECS 容器 vs EC2），与 [[ECS Deploy Runner]]（实体）共同构成跨账号部署完整链路。 **[[ctp-topic-16-cross-account-terraform-modules]]**（CTP Topic 16）：Fibos 主讲，多账号 AWS 环境中跨账号 Terraform 模块的中心化部署方案——解决原有 Gruntwork 流水线主要针对单账号设计、账号间直接互访存在安全风险（Blast Radius）的问题。核心架构：基于 **Shared Account（共享账号）** 作为中转站，Jenkins 托管于 Shared Account，检测到模块目录中 `cross-account.json` 标记文件后触发 **ECS Deploy Runner**（ECS 上的 Docker 容器）；该 Runner 通过 Assume Role 访问目标账号的两个角色——`TF state bucket accessor`（读取状态文件）和 `cross-account ECS deploy runner role`（执行资源部署）；角色切换逻辑在根目录 `terragrunt.hcl` 中全局配置。实现三大目标：**安全性**（无 Workload 账号间直接信任）、**自动化**（Jenkins 自动识别模块类型）、**可复用性**（模块代码不硬编码特定账号角色）。属 [[Infrastructure-as-Code]] 在多账号场景的进阶实践，与 [[ctp-topic-9-ci-cd-with-gruntwork]]（单账号流水线）构成演进关系，与 [[ctp-topic-32-using-atlantis-cicd-for-infrastructure-deployments]]（Atlantis 跨账号角色）共享 Assume Role 机制但执行载体不同（ECS 容器 vs EC2），与 [[ECS Deploy Runner]]（实体）共同构成跨账号部署完整链路。
**Learning Sessions Cloud Transformation Programme-Deploying RDS via Terraform**（2023 年，Greg，DBRE 团队）：Greg 来自 Database Reliability Engineering 团队，倡导通过 Terraform IaC 部署任何规模的 RDS 到 AWS，相比控制台具有速度、灵活性、一致性、灾难恢复、文档和自动化六大优势——**代码即文档**。RDS 部署提供两种模块选择：**裸 RDS module**（基础功能）和 **grunt work RDS Service**（推荐生产使用，预建 KMS 密钥加密和 CloudWatch 告警，SRE 核心模块功能弱于 grunt work）。**Terragrunt**（Terraform 封装器）用于保持代码整洁、避免变量重复声明，贯彻 DRY 原则；Day 2 运维（扩缩容、补丁、大版本升级）通过修改 Terragrunt 文件并提交 GitHub PR，由 Atlantis 自动应用变更。监控通过 CloudWatch Dashboard + Alarms 实现，需注意突发性能实例（burstable instance）的 CPU credits 消耗。属 [[Infrastructure-as-Code]] 在 RDS 数据库场景的实践，与 [[ctp-topic-48-terraform-vs-terragrunt]]（Terragrunt 推荐）和 [[ctp-topic-16-cross-account-terraform-modules]]（跨账号 Terraform 模块）共同构成 Terraform 生态知识链路，与 [[ctp-topic-9-ci-cd-with-gruntwork]]（Gruntwork CI/CD）共享 Gruntwork 模块体系。
**[[ctp-topic-12-using-ses-smtp-service-terraform-module]]**（CTP Topic 12）：Christian Deckelmann 和 Filos Christolakis 主讲，Micro Focus 团队使用 Terraform 模块自动化部署 AWS SES SMTP 服务以替代传统本地 SMTP 网关——随着业务向云端迁移，本地 SMTP 网关（如 smtbmicrofocus.com）已不再高效，SES 是网络安全部门唯一批准的云端邮件发送方案。Terraform 模块封装了 SMTP 终端节点配置，支持现有应用程序通过标准 SMTP 协议集成，无需重构代码适配 SES API；技术实现：在应用 VPC 中配置 VPC 端点实现私有连接（无需公网访问），通过 IAM 用户凭证作为 SMTP 认证信息并存储于 Secrets Manager，自动化完成 DKIM 验证和 Infoblox DNS 记录创建。两个关键手动步骤：① 申请脱离 SES Sandbox Mode（提交工单获取生产访问权限）以提升发送限额并允许向外部地址发信；② 手动更新 DNS TXT 记录以验证域名所有权（Terraform 难以处理多账号共享域名时对同一 TXT 记录值的追加操作）。未来计划：引入收件人地址限制和凭证滚动更新增强安全功能。与 [[ctp-topic-36-sendgrid-as-an-email-service]] 构成云邮件服务双路径——SendGrid 面向新标准，SES 服务现有应用平滑迁移。属 [[Infrastructure-as-Code]] 在邮件服务场景的实践，与 [[VPC-Endpoint]]、[[Secrets-Manager]] 概念关联。
**[[ctp-topic-21-supply-chain-security-in-micro-focus]]**（CTP Topic 21）： **[[ctp-topic-21-supply-chain-security-in-micro-focus]]**（CTP Topic 21）：
**[[ctp-topic-24-micro-focus-product-privacy-framework]]**（CTP Topic 24）：Micro Focus 产品隐私框架在云转型中的应用——PSAC（产品安全顾问委员会）与法律顾问合作，将 GDPR/CCPA 等晦涩法律条款翻译为约 110 项低级别技术要求；隐私框架是 STLC（安全开发生命周期）中 13 个安全与隐私轨道之一；通过五类需求（架构类/文档类/法律类/实现类/SAS 运营类）和成熟度模型（0-4 级）评估产品隐私合规状态；通过"蜘蛛图"直观展示产品在安全去标识化、被遗忘权、数据可移植性等 KPI 上的合规现状；最终产出标准化《产品隐私设置文档》，确保客户获得一致的隐私信息参考。属 [[Product Privacy Framework（产品隐私框架）]] 在 [[Micro Focus]] 云转型场景的核心实践，与 [[Micro Focus Security Development Life Cycle (STLC) Overview]]（STLC 整体架构）直接关联。 **[[ctp-topic-24-micro-focus-product-privacy-framework]]**（CTP Topic 24）：Micro Focus 产品隐私框架在云转型中的应用——PSAC（产品安全顾问委员会）与法律顾问合作，将 GDPR/CCPA 等晦涩法律条款翻译为约 110 项低级别技术要求；隐私框架是 STLC（安全开发生命周期）中 13 个安全与隐私轨道之一；通过五类需求（架构类/文档类/法律类/实现类/SAS 运营类）和成熟度模型（0-4 级）评估产品隐私合规状态；通过"蜘蛛图"直观展示产品在安全去标识化、被遗忘权、数据可移植性等 KPI 上的合规现状；最终产出标准化《产品隐私设置文档》，确保客户获得一致的隐私信息参考。属 [[Product Privacy Framework（产品隐私框架）]] 在 [[Micro Focus]] 云转型场景的核心实践，与 [[Micro Focus Security Development Life Cycle (STLC) Overview]]（STLC 整体架构）直接关联。

59
wiki/sources/ctp-topic-12-using-ses-smtp-service-terraform-module.md Normal file
View File

@@ -0,0 +1,59 @@
---
title: "CTP Topic 12 Using SES SMTP service terraform module"
type: source
tags:
- AWS
- Terraform
- SES
- Email
- CTP
- Cloud-Email
date: 2026-04-14
---
## Source File
- [[Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/ctp-topic-12-using-ses-smtp-service-terraform-module]]
## Summary（用中文描述）
- 核心主题：Micro Focus 团队使用 Terraform 模块自动化部署 AWS SES SMTP 服务，以替代传统的本地 SMTP 网关。
- 问题域：随着业务向云端迁移，使用本地 SMTP 网关（如 smtbmicrofocus.com）已不再高效，网络安全部门要求统一使用云端邮件发送方案。
- 方法/机制：在应用 VPC 中配置 VPC 终端节点以实现私有连接；通过 IAM 用户凭证作为 SMTP 认证信息并存储于 Secrets Manager；Terraform 模块自动化 SMTP 终端节点配置、DKIM 验证和 DNS 记录创建；支持现有应用程序通过标准 SMTP 协议集成，无需重构代码适配 SES API。
- 结论/价值：SES 是唯一获网络安全部门批准的云端邮件发送方案；Terraform 模块化封装降低了集成复杂度；需注意两个手动步骤（申请脱离 Sandbox Mode 和手动更新 DNS TXT 记录）。
## Key Claims（用中文描述）
- 在应用 VPC 中配置 VPC 终端节点，使应用可在不访问公网的情况下通过私有节点与 SES SMTP 服务通信。
- IAM 用户的 Access Key 和 Secret Key 被转换后作为 SMTP 认证的用户名和密码，相关凭证安全存储于 AWS Secrets Manager。
- Terraform 模块自动化完成 DKIM 验证和 Infoblox DNS 管理系统中域名所有权记录的创建。
- 手动更新 DNS TXT 记录以验证域名所有权仍是必需步骤，因 Terraform 难以处理多个 AWS 账号共享同一域名时对同一 TXT 记录值的追加操作。
- 脱离 SES Sandbox Mode（向 AWS 提交工单申请生产访问权限）是启用完整邮件发送能力的必要前提。
- SES 是 Micro Focus 网络安全部门唯一批准的云端邮件发送方案，替代了原有的本地 SMTP 网关。
## Key Quotes
> "随着业务向云端迁移，使用本地 SMTP 网关（如 smtbmicrofocus.com）已不再高效，SES 是目前网络安全部门唯一批准的云端邮件发送方案。" — Christian Deckelmann
> "SES Terraform 模块封装了 SMTP 终端节点的配置，方便现有应用程序通过标准的 SMTP 协议进行集成，而无需重构代码以适配 SES API。" — Filos Christolakis
## Key Concepts
- [[VPC-Endpoint]]：AWS 提供的私有连接服务，允许在 VPC 内部通过私有 IP 地址安全访问 AWS 服务，无需经过公网。
- [[DKIM-Email-Authentication]]：DomainKeys Identified Mail 的缩写，一种电子邮件验证标准，通过在邮件头部添加数字签名来防止欺诈和确保邮件完整性。
- [[Secrets-Manager]]：AWS 提供的凭证管理服务，用于安全地存储和检索 SES SMTP 的认证信息。
- [[SES-Sandbox-Mode]]：AWS SES 的默认限制状态，仅允许向已验证的地址发送少量邮件，需提交工单申请生产访问权限以提升发送限额。
## Key Entities
- [[AWS]]：Amazon Web Services，云服务提供商，SES（Simple Email Service）所属平台。
- [[Christian-Deckelmann]]：演讲者之一，分享 Micro Focus 在云转型中采用 SES SMTP 服务的背景与动机。
- [[Filos-Christolakis]]：演讲者之一，详细讲解 SES Terraform 模块的技术实现方案。
- [[Infoblox]]：公司内部使用的 DNS 管理系统，用于存放和管理验证域名所有权所需的 DNS 记录。
- [[VPC-Wrapper-Module]]：SES Terraform 模块所依赖的前置 VPC 配置模块，负责预先配置 SMTP VPC 终端节点。
## Connections
- [[VPC-Wrapper-Module]] ← depends_on ← [[ctp-topic-12-using-ses-smtp-service-terraform-module]]
- [[ctp-topic-12-using-ses-smtp-service-terraform-module]] ← extends ← [[AWS]]
- [[Terraform-And-Terragrunt-Best-Practices]] ← related_to ← [[ctp-topic-12-using-ses-smtp-service-terraform-module]]（Terragrunt Pre-hook/Post-hook 用于处理手动 DNS 验证步骤）
- [[ctp-topic-36-sendgrid-as-an-email-service]] ← alternative_to ← [[ctp-topic-12-using-ses-smtp-service-terraform-module]]（SendGrid 被选定为新 Landing Zone 标准，SES 用于现有应用迁移）
## Contradictions
- 与 [[ctp-topic-36-sendgrid-as-an-email-service]] 在邮件服务选型上的差异：
- 冲突点：两门课程分别介绍了不同的云邮件服务方案——SendGrid 被选定为标准云端邮件服务，而 SES 则专注于服务现有应用通过 SMTP 协议迁移上云。
- 当前观点：SES 通过 Terraform 模块封装现有应用 SMTP 接入路径，实现平滑迁移，无需修改应用代码。
- 对方观点：SendGrid 作为新标准云邮件服务，提供更高上限（每封 1,000 收件人 vs SES 每封 50 收件人）、更简单的 API 集成和全球中继节点。

55
wiki/sources/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi.md Normal file
View File

@@ -0,0 +1,55 @@
---
title: "Learning Sessions Cloud Transformation Programme-20230808 183322-Meeting Recording"
type: source
tags:
- Terraform
- CTP
- IaC
date: 2023-08-08
---
## Source File
- [[Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi]]
## Summary（用中文描述）
- 核心主题：通过 Terraform IaC 实现 ECS 容器化应用的自动化部署
- 问题域：企业在不可预测性和敏捷性需求下的基础设施挑战
- 方法/机制：基于 Gruntwork 仓库构建 ECS Terraform 模块，支持 Docker 容器/EC2 部署，具备自动扩缩容、自动故障恢复、金丝雀部署能力；采用 Listener 集中管理方式
- 结论/价值：CTP/SRE 团队通过 IaC 实现 ECS 部署标准化，与 AWS 服务深度集成
## Key Claims（用中文描述）
- 企业必须在不可预测性和敏捷性需求之间找到平衡，基础设施即代码（IaC）是应对这一挑战的关键手段
- ECS（Elastic Container Service）是 AWS 原生技术，与 AWS 服务深度集成，相比 EKS 或原生 Kubernetes 有其独特优势与挑战
- CTP/SRE 团队基于 Gruntwork 仓库构建了可复用的 ECS Terraform 模块，支持 Docker 容器作为逻辑单元
- ECS 模块支持 EC2 实例或目标部署，具备自动扩缩容、自动故障恢复、金丝雀部署功能
- Listener 集中管理方式避免了各产品直接下载 Gruntwork 模板并本地使用的碎片化问题
- ECS 部署的前置条件包括 VPC、ELB 安全组和 EFS 卷挂载
- 模块支持通过 YAML 或 JSON 传递配置，集成 CloudWatch、Splunk、Grafana 和 Prometheus
## Key Quotes
> "Businesses have to thrive in the middle of all these challenges and it is forged by code." — JP，阐述企业面临的不可预测性挑战与 IaC 的核心价值
> "We have implemented the listener approach because we have seen many of the products are downloading the quotes from the Gruntwork and using locally." — Raja M，说明 Listener 集中管理模式的动机
## Key Concepts
- [[Infrastructure-as-Code]]：通过代码定义和管理基础设施，实现自动化、可重复、可审计的部署流程
- [[Canary-Deployment]]：金丝雀部署，通过逐步将流量切换到新版本，降低新版本上线的风险
- [[ECS-Module]]：CTP/SRE 团队基于 Gruntwork 仓库构建的 ECS Terraform 模块
## Key Entities
- [[JP]]：主讲人之一，介绍 ECS 的业务和技术背景
- [[Raja-M]]：CTP/SRE 团队成员，详细讲解 ECS 模块的构建方式
- [[Gruntwork]]：提供 Terraform 模块的基础仓库，CTP 在其基础上构建了 ECS 模块
- [[AWS]]：云服务提供商，ECS 为 AWS 弹性容器服务
- [[Cloud-Transformation-Programme]]：云转型计划，组织发起的基础设施现代化计划
## Connections
- [[learning-sessions-ecs-deployment-using-iac-20230808-183322-meeting-recording]] ← same_topic ← [[learning-sessions-ecs-deployment-using-iac-20230808-183322-meeting-recording]]
- [[Infrastructure-as-Code]] ← implements ← [[Cloud-Transformation-Programme]]
- [[ECS-Module]] ← based_on ← [[Gruntwork]]
## Contradictions
- 与 [[ctp-topic-64-scaling-out-with-amazon-eks]] 在容器编排选型上存在差异：
- 冲突点：ECS 强调 AWS 原生集成，EKS 强调可移植性
- 当前观点：ECS 与 AWS 服务深度集成，适合追求 AWS 原生体验的场景
- 对方观点：EKS 基于原生 Kubernetes，提供更好的跨云可移植性
- 结论：两者适用于不同场景，可根据业务需求互补使用

57
wiki/sources/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform.md Normal file
View File

@@ -0,0 +1,57 @@
---
title: "Learning Sessions Cloud Transformation Programme-Deploying RDS via Terraform"
type: source
tags: [Terraform, RDS, IaC, CTP, DevOps, DBRE, AWS]
date: 2026-04-14
---
## Source File
- [[Cloud & DevOps/Public-Cloud-Learning-Sessions/03_Terraform/learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform]]
## Summary（用中文描述）
- 核心主题：**通过 Terraform 在 AWS 上部署 RDS 数据库**，涵盖 IaC 最佳实践和 Gruntwork RDS 模块的选型对比
- 问题域：RDS 部署方式的选择（控制台 vs 代码）、模块选型（grunt work 模块 vs SRE 核心模块）、Day 2 运维（扩缩容/补丁/升级）
- 方法/机制：使用 Terragrunt（Terraform 封装器）管理 RDS 部署，通过 GitHub PR + Atlantis 实现变更自动化；CloudWatch 负责监控告警
- 结论/价值：IaC 部署任何规模的 RDS 到 AWS 均优于控制台；grunt work RDS Service 相比裸模块提供更完整的企业级功能（KMS 加密、CloudWatch 告警等）；代码即文档
## Key Claims（用中文描述）
- **IaC 六大大好处**：速度、灵活性、一致性、灾难恢复、文档、自动化。代码即文档
- **两种 RDS 部署选项**：裸模块 RDS module（基础功能）vs 更完整的 grunt work RDS Service（推荐，预建 KMS 加密和 CloudWatch 告警）
- **SRE 核心模块功能弱于 grunt work 服务**：建议生产环境使用 grunt work RDS Service
- **Terragrunt 优于裸 Terraform**：避免变量重复声明，保持代码整洁，贯彻 DRY 原则
- **Day 2 运维通过 GitHub PR + Atlantis 实现**：扩缩容、补丁、大版本升级均在 Terragrunt 文件中修改，通过 PR 触发 Atlantis 自动应用
- **监控方案**：CloudWatch Dashboard + Alarms，注意突发性能实例（burstable instance）的 CPU credits 消耗
## Key Quotes
> "We use Terragrunt, which is basically it's a wrapper around Terraform, and it allows you to keep your code clean and you're not repeating your variables all the time." — Greg, DBRE Team
> "The code is the documentation." — Greg, 强调 IaC 的文档价值
## Key Concepts
- [[Infrastructure-as-Code]]：通过代码定义和版本控制基础设施资源，核心优势包括速度、一致性、灾难恢复和自动化
- [[DRY Principle]]：Terragrunt 通过管理 provider 和 remote_state 块减少跨环境重复声明
- [[GitOps]]：通过 GitHub PR + Atlantis 实现基础设施变更的自动化审核和应用
- [[CloudWatch-Alarms]]：RDS 监控与告警机制，包含突发性能实例的 CPU credits 考虑
- [[KMS-Encryption]]：grunt work RDS Service 内置的 KMS 密钥加密功能
## Key Entities
- [[Gruntwork]]：提供预建 Terraform 模块（RDS Service 等），建议生产环境使用其 grunt work RDS Service 而非裸模块
- [[Atlantis]]：Git 驱动的 Terraform 自动化工具，配合 GitHub PR 实现 IaC 变更
- [[Terraform]]：云厂商无关的 IaC 核心工具
- [[Terragrunt]]：Terraform 的 DRY 封装层，用于管理 RDS 部署配置
- [[DBRE]]：Database Reliability Engineering 团队，Greg 来自该团队
- [[CloudWatch]]：AWS 监控服务，用于 RDS Dashboard 和 Alarms
## Connections
- [[learning-sessions-cloud-transformation-programme-20230808-183322-meeting-recordi]] ← related ← [[learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform]]（同一 CTP 系列，ECS 部署 + RDS 部署）
- [[ctp-topic-48-terraform-vs-terragrunt]] ← related ← [[learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform]]（Terragrunt 在两个主题中均有讨论）
- [[ctp-topic-16-cross-account-terraform-modules]] ← related ← [[learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform]]（IaC 模块化 + Cross-account Terraform）
- [[ctp-topic-9-ci-cd-with-gruntwork]] ← foundation ← [[learning-sessions-cloud-transformation-programme-deploying-rds-via-terraform]]（Gruntwork CI/CD 基础）
- [[Terraform]] ← wraps ← [[Terragrunt]]
- [[Gruntwork]] ← provides ← [[RDS-Module]]（grunt work RDS Service）
- [[Atlantis]] ← automates ← [[Terraform]]
- [[CloudWatch]] ← monitors ← [[RDS-Module]]
## Contradictions
- 与 [[ctp-topic-9-ci-cd-with-gruntwork]]（Gruntwork CI/CD）：两者均依赖 Gruntwork 模块体系；本主题聚焦 RDS 部署，CI/CD 主题聚焦 ECS 应用部署；RDS 部署同样适用 Gruntwork 流水线规范，两者互补而非冲突
- 与 [[ctp-topic-48-terraform-vs-terragrunt]]（Terraform vs Terragrunt）：本主题的实际案例印证了该主题的观点——Terragrunt 保持代码整洁、避免变量重复；两主题一致，共同推荐 Terragrunt 作为 Terraform 的封装层
- 与 [[ctp-topic-16-cross-account-terraform-modules]]（跨账号 Terraform 模块）：两者均讨论 Terraform 模块的运维方式；跨账号模块方案（Jenkins + ECS Deploy Runner）与本主题（RDS 通过 Atlantis）的 CI/CD 载体不同，适用于不同规模和架构场景，无直接冲突