From 98cd6b71cb2d9bdc4a7b3d5514bdd0ede7279737 Mon Sep 17 00:00:00 2001 From: Timmy Date: Wed, 1 Apr 2026 15:38:32 +0800 Subject: [PATCH] docs: add README.md, QUICKSTART.md, SUMMARY.md for K3s maintenance --- QUICKSTART.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 143 ++++++++++++++++++++++++++++++-------- SUMMARY.md | 130 ++++++++++++++++++++++++++++++++++ 3 files changed, 432 insertions(+), 30 deletions(-) create mode 100644 QUICKSTART.md create mode 100644 SUMMARY.md diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..e98c5d9 --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,189 @@ +# K3s 叢集 - 快速入門 + +新手友善的 K3s 維護指南 + +## 🚀 快速開始 + +### 連線到叢集 + +```bash +ssh ubuntu@192.168.42.120 +sudo -i +cd /root/k8s +``` + +--- + +## 📦 服務管理 + +### 部署服務 + +```bash +cd apps// +./deploy.sh +``` + +例如部署 CodiMD： +```bash +cd /root/k8s/apps/codimd +./deploy.sh +``` + +### 查看服務狀態 + +```bash +cd apps// +./status.sh +``` + +輸出包含： +- Pods 狀態 +- Services 狀態 +- PVC 儲存狀態 +- Ingress 入口 +- 資料庫連通性（如適用） + +### 停止服務（保留資料） + +```bash +cd apps// +./stop.sh +``` + +⚠️ 注意：`stop.sh` 只刪除 Deployment/Service/Ingress，**PVC 和 Secret 會保留** + +--- + +## 💾 備份與還原 + +### 備份服務 + +```bash +cd apps// +./backup.sh +``` + +備份位置： +- CodiMD → `apps/codimd/backup/` +- Opengist → `apps/opengist/backup/` +- PostgreSQL → `apps/postgres/backups/` + +### 還原服務 + +```bash +cd apps// +./restore.sh +``` + +⚠️ 還原前請先停止服務 + +--- + +## 🔍 叢集診斷 + +### 檢查節點狀態 + +```bash +cd /root/k8s/cluster +./check_nodes.sh +``` + +### 檢查儲存空間 + +```bash +cd /root/k8s/cluster +./check_storage.sh +``` + +### 檢查存取權限 + +```bash +cd /root/k8s/cluster +./check_access.sh +``` + +--- + +## 🛠️ 常見問題排查 + +### Pod 無法啟動？ + +```bash +# 查看 Pod 狀態 +kubectl get pods + +# 查看詳細資訊 +kubectl describe pod + +# 查看日誌 +kubectl logs +``` + +### 服務無法連線？ + +```bash +# 檢查 Service +kubectl get svc + +# 檢查 Endpoints（是否有 Pod 掛上） +kubectl get endpoints + +# 檢查 Ingress +kubectl get ingress +``` + +### 儲存空間不足？ + +```bash +# 檢查 Longhorn volumes +kubectl get pv -A +kubectl get pvc -A + +# 檢查節點磁碟 +df -h +``` + +--- + +## 📝 修改 Manifests + +1. **本地編輯**：在 `/Users/timmy/42_120/k8s/` 修改 yaml +2. **同步到遠端**： + ```bash + rsync -avz --rsync-path="sudo rsync" \ + /Users/timmy/42_120/k8s/ \ + ubuntu@192.168.42.120:/root/k8s/ + ``` +3. **應用變更**： + ```bash + cd /root/k8s/apps/ + kubectl apply -f manifests/ + ``` + +--- + +## 🔄 Git 版控工作流程 + +```bash +# 本地 +cd /Users/timmy/42_120/k8s +git add -A +git commit -m "描述變更" +git push + +# 確認遠端已有變更後，再同步到 K3s 主機 +``` + +--- + +## 📋 服務清單速查 + +| 服務 | 目錄 | deploy | stop | status | backup | +|------|------|--------|------|--------|--------| +| CodiMD | `apps/codimd/` | ✅ | ✅ | ✅ | ✅ | +| Opengist | `apps/opengist/` | ✅ | ✅ | ✅ | ✅ | +| PostgreSQL | `apps/postgres/` | ✅ | ✅ | ✅ | ✅ | + +--- + +💡 **提示**：執行任何腳本前，先用 `./status.sh` 確認目前狀態！ diff --git a/README.md b/README.md index 13389e5..0ba41f6 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,118 @@ -# K8s 叢集維護記錄 +# K3s 叢集管理 -## 連線資訊 -- **主機**: 192.168.42.120 -- **帳號**: ubuntu (SSH Key 登入) -- **sudo**: `sudo -i` 可直接成為 root +> 個人 K3s Kubernetes 叢集的 manifests 與維護腳本 -## K3s 目錄 -- **遠端**: `/root/k8s` -- **本地**: `/Users/timmy/42_120/k8s` +## 📖 文檔導航 -## 已部署服務 - -### CodiMD (筆記應用) -- manifests: `apps/codimd/manifests/` -- 備份: `apps/codimd/backup/` -- 腳本: deploy.sh, stop.sh, status.sh, backup.sh, restore.sh - -### Opengist (Git Snippets) -- manifests: `apps/opengist/manifests/` -- 備份: `apps/opengist/backup/` -- 腳本: deploy.sh, stop.sh, status.sh, backup.sh, restore.sh - -### PostgreSQL (資料庫) -- manifests: `apps/postgres/manifests/` -- 備份: `apps/postgres/backups/` -- 腳本: deploy.sh, stop.sh, status.sh, backup.sh - -## 叢集工具 -- `cluster/check_access.sh` - 檢查存取權限 -- `cluster/check_nodes.sh` - 檢查節點狀態 -- `cluster/check_storage.sh` - 檢查儲存空間 +| 文檔 | 用途 | +|------|------| +| **[SUMMARY.md](SUMMARY.md)** | 📋 服務總覽、快速參考 | +| **[QUICKSTART.md](QUICKSTART.md)** | 🚀 快速入門、操作指南 | --- -⚠️ 維護時請同步更新本地與遠端檔案 + +## 🖥️ 連線資訊 + +```bash +ssh ubuntu@192.168.42.120 +sudo -i # 切換 root +cd /root/k8s # K3s 工作目錄 +``` + +- **主機**: 192.168.42.120 +- **K3s 目錄**: `/root/k8s` +- **本地目錄**: `/Users/timmy/42_120/k8s` +- **Git Repo**: http://192.168.42.124:31337/timmy/k3s.git + +--- + +## 🚀 已部署服務 + +| 服務 | 用途 | 狀態腳本 | +|------|------|----------| +| [CodiMD](apps/codimd/) | Markdown 協作筆記 | `./apps/codimd/status.sh` | +| [Opengist](apps/opengist/) | Git Snippets 管理 | `./apps/opengist/status.sh` | +| [PostgreSQL](apps/postgres/) | 通用資料庫 | `./apps/postgres/status.sh` | + +--- + +## 📂 目錄結構 + +``` +k8s/ +├── apps/ +│ ├── codimd/ # 筆記應用 +│ ├── opengist/ # Git Snippets +│ └── postgres/ # 資料庫 +└── cluster/ # 叢集工具 +``` + +每個 app 都包含： +- `manifests/` - Kubernetes YAML 檔案 +- `backup/` - 備份資料 +- `deploy.sh` - 部署腳本 +- `stop.sh` - 停止腳本（保留資料） +- `status.sh` - 狀態檢查 +- `backup.sh` - 備份腳本 + +--- + +## ⚡ 快速命令 + +```bash +# 部署所有服務 +for app in apps/*/; do cd "$app" && ./deploy.sh && cd ../..; done + +# 檢查所有服務狀態 +for app in apps/*/; do cd "$app" && ./status.sh && cd ../..; done + +# 查看 K3s Pods +kubectl get pods -A + +# 查看 Ingress +kubectl get ingress -A +``` + +--- + +## 🔧 維護工作流程 + +1. **本地修改** → 在此目錄編輯 manifests 或腳本 +2. **Git 提交** → `git add -A && git commit -m "描述" && git push` +3. **同步遠端** → `rsync -avz --rsync-path="sudo rsync" . ubuntu@192.168.42.120:/root/k8s/` +4. **套用變更** → `kubectl apply -f manifests/` + +--- + +## 📚 叢集架構 + +``` +┌─────────────────────────────────────┐ +│ Traefik Ingress │ +│ (note.xxx.com / git.xxx.com) │ +└─────────────────┬───────────────────┘ + │ + ┌─────────────┼─────────────┐ + │ │ │ +┌───▼───┐ ┌───▼───┐ ┌───▼───┐ +│ CodiMD│ │Opengist│ │PostgreSQL +│ + │ │ │ │ (獨立) +│ PG │ │ │ │ +└───────┘ └────────┘ └───────┘ + │ │ │ +└───▼─────────────▼─────────────▼───┘ + Longhorn Storage + (持久化資料儲存) +``` + +--- + +## 🔗 相關連結 + +- [K3s 官方文檔](https://docs.k3s.io/) +- [Traefik Ingress](https://doc.traefik.io/traefik/) +- [Longhorn Storage](https://longhorn.io/) + +--- + +⚠️ **注意**：維護時請同步本地與遠端，並定期執行備份！ diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..b787577 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,130 @@ +# K3s 叢集總覽 + +快速參考手冊 - 所有服務一覽 + +## 🖥️ 叢集資訊 + +| 項目 | 值 | +|------|-----| +| 主機 | 192.168.42.120 | +| 連線 | `ssh ubuntu@192.168.42.120` → `sudo -i` | +| K8s 目錄 | `/root/k8s` | +| 本地目錄 | `/Users/timmy/42_120/k8s` | +| Git Repo | http://192.168.42.124:31337/timmy/k3s.git | + +--- + +## 🚀 已部署服務 + +### CodiMD - 協作筆記應用 + +| 項目 | 值 | +|------|-----| +| 用途 | Markdown 協作筆記、團隊知識庫 | +| Ingress | `note.yourdomain.com` | +| 命名空間 | `default` | +| 資料庫 | PostgreSQL (內建) | + +**組件：** +- `codimd-app` - 應用程式 +- `codimd-db` - PostgreSQL 資料庫 +- Longhorn PVC - 資料持久化 + +**腳本：** `apps/codimd/{deploy,stop,status,backup,restore}.sh` + +--- + +### Opengist - Git Snippets 管理 + +| 項目 | 值 | +|------|-----| +| 用途 | 自架 Git snippets、程式碼片段分享 | +| SSH Port | `2222` (Traefik TCP) | +| Web Port | `80`/`443` (Ingress) | +| 命名空間 | `default` | + +**組件：** +- `opengist` - 應用程式 +- Longhorn PVC - 資料持久化 + +**腳本：** `apps/opengist/{deploy,stop,status,backup,restore}.sh` + +--- + +### PostgreSQL - 獨立資料庫 + +| 項目 | 值 | +|------|-----| +| 用途 | 通用 PostgreSQL 資料庫服務 | +| Service | `postgres:5432` | +| 命名空間 | `default` | + +**腳本：** `apps/postgres/{deploy,stop,status,backup}.sh` + +--- + +## 📂 目錄結構 + +``` +k8s/ +├── apps/ +│ ├── codimd/ # CodiMD 筆記應用 +│ │ ├── manifests/ # K8s YAML 檔案 +│ │ ├── backup/ # 備份檔案 +│ │ ├── tmpdir/ # 暫存/舊檔案 +│ │ └── *.sh # 管理腳本 +│ ├── opengist/ # Opengist Git Snippets +│ │ ├── manifests/ +│ │ ├── backup/ +│ │ └── *.sh +│ └── postgres/ # 獨立 PostgreSQL +│ ├── manifests/ +│ ├── backups/ # SQL 備份 +│ └── *.sh +└── cluster/ # 叢集檢查工具 + ├── check_access.sh # 檢查存取權限 + ├── check_nodes.sh # 檢查節點狀態 + └── check_storage.sh # 檢查儲存空間 +``` + +--- + +## 🔧 常用 K3s 命令 + +```bash +# 連線後切換 root +ssh ubuntu@192.168.42.120 +sudo -i + +# 查看 Pods +kubectl get pods -A + +# 查看 Services +kubectl get svc -A + +# 查看 Ingress +kubectl get ingress -A + +# 查看 PVC +kubectl get pvc -A + +# 進入 Pod +kubectl exec -it -- sh + +# 查看日誌 +kubectl logs -f +``` + +--- + +## 🔄 維護工作流程 + +1. **本地修改** → 編輯 manifests 或腳本 +2. **同步遠端** → `rsync` 或 `git push` +3. **部署** → 執行 `deploy.sh` +4. **驗證** → 執行 `status.sh` +5. **備份** → 執行 `backup.sh` + +--- + +📖 詳細操作請參考 [QUICKSTART.md](QUICKSTART.md)