新增分拆文件、SOP 與 Caddy SSL 憑證更新紀錄

- 將 hospital_media_antmedia.md 分拆為 docs/ 下五份主題文件
  (host.md, caddy.md, antmedia.md, ssl.md, maintenance.md)
- 新增 README.md / QUICKSTART.md / SUMMARY.md 作為文件入口
- 新增 SOP:Caddy SSL 憑證更新流程 (docs/sop-update-caddy-ssl.md)
  含 2026-04-16 實戰踩坑紀錄(.cer 副檔名、私鑰不匹配、sudo、防火牆 TLS 終端)
- 更新各文件中 tel.tpech.gov.tw 憑證資訊:HiPKI → TWCA,到期 2026-10-30
- 新增 .gitignore 排除 ssl-staging/(含私鑰,不可進 git)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-16 10:54:47 +08:00
parent 7d6a7ef848
commit 97fd841a0c
10 changed files with 1013 additions and 0 deletions

112
docs/ssl.md Normal file
View File

@@ -0,0 +1,112 @@
# SSL 憑證管理
## 憑證總覽
兩張憑證分屬不同 CA需各自手動更新。
| 網域 | CA | 到期日 | 使用於 |
|------|----|--------|--------|
| `tel.tpech.gov.tw` | **TWCA**2026-04-16 起) | **2026-10-30** | [Caddy 反向代理](caddy.md) |
| `tel-server.tpech.gov.tw` | 中華電信 HiPKI | 2026-04-23 | [Ant Media Server](antmedia.md) |
> `tel.tpech.gov.tw` 這次只有半年效期4/1510/302026-10 前需再次更新。
## AMS 憑證資訊
| 項目 | 值 |
|------|-----|
| 網域 | `tel-server.tpech.gov.tw` |
| 簽發者 | 中華電信 HiPKI OV TLS CA - G1 |
| 有效期 | 2025-04-23 ~ 2026-04-23 |
| 憑證位置(容器內) | `/usr/local/antmedia/conf/fullchain.pem``privkey.pem``chain.pem` |
| Keystore 密碼 | 網域名稱 `tel-server.tpech.gov.tw`(由容器內 `enable_ssl.sh``generate_password` 決定) |
## 更新 AMS SSL 憑證
### 方法一:使用 `/opt/antmediaserver/enable_ssl.sh`(推薦)
將新的 fullchain.pem + key 放入憑證資料夾,然後一行搞定:
```bash
# 把憑證檔案放到對應資料夾(資料夾內需有 fullchain.pem 和 tel_server_tpech_gov_tw.key
cd /opt/antmediaserver
./enable_ssl.sh ssl_tel_server_tpech_gov_tw_2025
# 或指定網域
./enable_ssl.sh ssl_tel_server_tpech_gov_tw_2025 tel-server.tpech.gov.tw
```
此腳本會自動:`docker cp` 憑證進容器 → 在容器內執行 `enable_ssl.sh` 生成 keystore/truststore 並重啟 AMS。
### 方法二:手動操作
1. 準備 PEM 檔:`fullchain.pem`(伺服器憑證 + 中繼 CA`privkey.pem``chain.pem`(中繼 CA
如果拿到的是 `.cer`DER 格式),先轉換:
```bash
openssl x509 -inform der -in certificate.cer -out certificate.pem
cat server.pem intermediate_ca.pem > fullchain.pem
cp intermediate_ca.pem chain.pem
```
2. 複製進容器並執行:
```bash
docker cp fullchain.pem antmedia:/usr/local/antmedia/
docker cp privkey.pem antmedia:/usr/local/antmedia/
docker cp chain.pem antmedia:/usr/local/antmedia/
docker exec -it antmedia bash -c "cd /usr/local/antmedia && ./enable_ssl.sh \
-d tel-server.tpech.gov.tw \
-f /usr/local/antmedia/fullchain.pem \
-p /usr/local/antmedia/privkey.pem \
-c /usr/local/antmedia/chain.pem"
```
### 驗證
```bash
openssl s_client -connect tel-server.tpech.gov.tw:5443 -servername tel-server.tpech.gov.tw < /dev/null 2>/dev/null | openssl x509 -noout -dates
```
## 更新 Caddy 憑證
詳見 [caddy.md](caddy.md#更新-caddy-憑證)。
## 年度 SSL 更新 checklist
### 步驟一網域驗證DCV
中華電信 HiPKI 簽發憑證前,會要求透過 HTTP 驗證網域所有權。驗證檔案放在:
```
/opt/caddy/tel-server/.well-known/pki-validation/
├── DN_CHECK_FILE.htm # HiPKI DCV 驗證檔JSON 格式,含 randomNumber + expireTime
└── whois.txt # 域名所有權驗證
```
Caddy 中 `tel-server.tpech.gov.tw:80` 設定為靜態檔案服務,就是為了讓 CA 能存取:
`http://tel-server.tpech.gov.tw/.well-known/pki-validation/DN_CHECK_FILE.htm`
流程:
1. 向中華電信提交 CSR 申請憑證
2. 中華電信會提供新的驗證檔案內容
3. 更新 `/opt/caddy/tel-server/.well-known/pki-validation/` 下的檔案
4. 等待 CA 驗證通過後取得新憑證
### 步驟二:安裝新憑證
1. 更新 Caddy 憑證:覆蓋 `/opt/caddy/fullchain.pem` + `privkey.pem` → `./restart.sh`
2. 更新 AMS 憑證:`cd /opt/antmediaserver && ./enable_ssl.sh ssl_tel_server_tpech_gov_tw_<年份>`
3. 備份新憑證到 `/opt/caddy/hospital/` 和 `/opt/antmediaserver/ssl_tel_server_tpech_gov_tw_<年份>/`
4. 備份 AMS 資料:`cd /opt/antmediaserver && ./backup_antmedia_data.sh`
## 具體 SOP
- [SOP更新 Caddy `tel.tpech.gov.tw` 憑證TWCA](sop-update-caddy-ssl.md) — 照著跑
## 相關文件
- [Caddy 反向代理](caddy.md)
- [Ant Media Server](antmedia.md)
- [系統維護與備份](maintenance.md)