214 lines
7.6 KiB
Markdown
214 lines
7.6 KiB
Markdown
# apps/backend
|
||
|
||
Harbor Desk Phase C（go-zero）。
|
||
|
||
## 原則
|
||
|
||
| 做 | 不做 |
|
||
|----|------|
|
||
| `generate/api` + `make gen-api` | 手寫 handler／routes |
|
||
| `generate/database/mongo` + `make migrate-up` | 在 gateway 啟動時隱式建 index／seed |
|
||
| `monc` + `CacheRedis` | 自己半套 mongo cache |
|
||
| `internal/logic` + `module/*/domain|repository|usecase` | 業務塞進 handler |
|
||
|
||
## 指令
|
||
|
||
```bash
|
||
cd apps/backend
|
||
make build # gateway + worker
|
||
make start # build 後背景啟動 gateway + worker（PID/log 在 /tmp/haixun）
|
||
make stop
|
||
make restart
|
||
make test
|
||
make gen-api # 改 .api 後
|
||
make migrate-up # 改 generate/database 後
|
||
make init # 只建立可重複執行的 operational indexes
|
||
make seeder # 讀 etc/gateway.yaml 的 Seed.AdminPassword
|
||
make crawler-install # 安裝 dev_mode Chrome crawler 的 Playwright/Chromium
|
||
SCOUT_CRAWLER_TOKEN='...' make crawler-start
|
||
SCOUT_CRAWLER_TOKEN='...' make crawler-restart
|
||
make tidy
|
||
```
|
||
|
||
### Scout Chrome Crawler
|
||
|
||
`dev_mode=true` 時，Scout 只走私有 Playwright crawler，沒有同步有效 Chrome session 就會要求使用者先同步。
|
||
|
||
1. 在私有 `etc/gateway.yaml` 填 `Scout.SessionSecret`、`Scout.CrawlerEndpoint`、`Scout.CrawlerToken`。
|
||
2. 執行 `make crawler-install` 一次。
|
||
3. 執行 `SCOUT_CRAWLER_TOKEN='與 Scout.CrawlerToken 相同的值' make crawler-start`。
|
||
4. crawler 必須維持 `127.0.0.1` 私網綁定，禁止公開反向代理。
|
||
|
||
詳見 [`crawler/README.md`](crawler/README.md)。
|
||
|
||
```bash
|
||
# 需要 Mongo + Redis（go-zero monc / redis）
|
||
# 私有設定只放在 etc/gateway.yaml（此檔不會被 git 追蹤）：
|
||
# cp etc/gateway.example.yaml etc/gateway.yaml
|
||
# 填入 Mongo/Redis/MinIO 密碼與兩組不同的 JWT secret。
|
||
# Mongo 若有帳密（本機 infra 常見），一定要帶進 URI：
|
||
MONGO_URL='mongodb://USER:PASS@127.0.0.1:27017/haixun?authSource=admin' make migrate-up
|
||
go run . -f etc/gateway.yaml
|
||
# Seed.AdminPassword 填好後執行 make seeder（uid=1000000 → 顯示 01000000）
|
||
```
|
||
|
||
### 日誌與密碼（安全）
|
||
|
||
| 禁止出現在 log | 說明 |
|
||
|----------------|------|
|
||
| `password` / `new_password` / `current_password` / `temporary_password` | 明碼 |
|
||
| `password_hash` | bcrypt 也不可打 log |
|
||
| access/refresh token、api_key | 憑證 |
|
||
|
||
實作：
|
||
|
||
- 啟動時 `securelog.SilenceMongo()` → 關閉 go-zero **mon** 文件 dump（否則 ReplaceOne 會印出整份 member）
|
||
- `RestConf.Verbose = false` → 不印 request body
|
||
- 自寫 log 請用 `securelog.RedactAny(v)` / 勿 `logx.Infof("%+v", req)`
|
||
|
||
HTTP access log 只記 method/path/status/duration，不含 body。
|
||
|
||
### 物件儲存（頭像）— **僅 MinIO/S3**
|
||
|
||
不落本機磁碟（無 localstore / `/files`）。未設定 Endpoint 時 upload 直接失敗。
|
||
|
||
| 項目 | 說明 |
|
||
|------|------|
|
||
| API | `POST /api/v1/media/upload`（需 JWT）`{ content: dataURL, kind: "avatar" }` |
|
||
| 回傳 | `{ url, key }` — Mongo member **只存 url** |
|
||
| 後端 | MinIO（dev）或 S3（prod），S3 API + path-style |
|
||
| env | `HAIXUN_STORAGE_S3_*` 或 `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` |
|
||
|
||
```yaml
|
||
ObjectStorage:
|
||
Endpoint: "http://127.0.0.1:9000" # 必填
|
||
Bucket: "haixun-assets"
|
||
AccessKey: "haixun"
|
||
SecretKey: "..."
|
||
UsePathStyle: true
|
||
PublicBaseURL: "" # 或 CDN / 反向代理公開前綴
|
||
```
|
||
|
||
FE：選頭像 → upload → URL → `PATCH profile`（禁止 data URL）。
|
||
|
||
### 密碼政策（前後端一致）
|
||
|
||
| 規則 | 說明 |
|
||
|------|------|
|
||
| 長度 | **≥ 12** 字元 |
|
||
| 組成 | **大寫 + 小寫 + 數字 + 符號** 皆須至少一個 |
|
||
| 後端 | `ValidatePasswordPolicy` → 不符回 **400003** + `domain.PasswordPolicyEN` |
|
||
| 前端 | `passwordPolicy.ts` + 語言包 `password.policy.hint` / `api.err.400003` |
|
||
|
||
**同一句說明：**
|
||
|
||
- EN: `Password must be at least 12 characters with upper, lower, digit, and symbol`
|
||
- ZH: `密碼須至少 12 碼，且含大寫、小寫、數字與符號`
|
||
|
||
前端依 code 400003 顯示語系文案；placeholder／hint／錯誤都用同一 key，勿另寫一句。
|
||
|
||
### 寄信（信箱驗證 / 重設密碼）
|
||
|
||
業務在 `internal/logic/auth/*`：產碼 → `Notification.RenderVerify` → `SendEmail`。
|
||
寄送實作在 `internal/module/notification`（SMTP，Mailgun 相容）。
|
||
|
||
#### 模板與多語
|
||
|
||
- 引擎與 stand-alone 相同：**hermes**（`github.com/matcornic/hermes/v2`）
|
||
- 語系：`zh-TW`（預設）／`en`；來源為會員 `preferred_language`，忘記密碼則用請求 `language`（FE 當前 locale）
|
||
- Logo：`Brand.LogoURL` 或預設 `{PublicWebBase}/brand-mark.jpg`（`apps/web/public/brand-mark.jpg`）
|
||
|
||
```yaml
|
||
PublicWebBase: "http://127.0.0.1:5173"
|
||
Brand:
|
||
Name: "Harbor Desk"
|
||
LogoURL: "" # 空 = PublicWebBase/brand-mark.jpg
|
||
Copyright: "© Harbor Desk"
|
||
```
|
||
|
||
#### 本機：Mailpit（推薦）
|
||
|
||
```bash
|
||
# 已含在 old/infra docker-compose（mongo/redis/mailpit）
|
||
cd old/infra && docker compose --env-file ../deploy/.env.dev up -d mailpit
|
||
|
||
# UI 看信
|
||
open http://127.0.0.1:8025
|
||
```
|
||
|
||
| 項目 | 值 |
|
||
|------|-----|
|
||
| SMTP | `127.0.0.1:1025`（無密碼也可；可開 AUTH accept-any 模擬 Mailgun） |
|
||
| Web UI | http://127.0.0.1:8025 |
|
||
| gateway 預設 | `Mail.SMTP.Host=127.0.0.1` `Port=1025` |
|
||
|
||
呼叫 `POST /api/v1/auth/email/send-code` 或 `password/request-reset` 後，到 Mailpit UI 看 HTML 信。
|
||
#### 正式：Mailgun SMTP
|
||
|
||
```yaml
|
||
Mail:
|
||
Sender: "Harbor Desk <noreply@your-domain.com>"
|
||
SMTP:
|
||
Host: "smtp.mailgun.org"
|
||
Port: 587
|
||
User: "postmaster@YOUR_DOMAIN"
|
||
Password: "<Mailgun SMTP password>"
|
||
DevExposeCode: false
|
||
```
|
||
|
||
同一套 `Mail.SMTP` 設定；本機指 Mailpit、上線指 Mailgun，**code 不用改**。
|
||
|
||
env 覆寫：`MAIL_SMTP_*` 或 `HAIXUN_SMTP_*`（與 `old/deploy/.env.dev` 相容）。
|
||
|
||
| SMTP Host | 行為 |
|
||
|-----------|------|
|
||
| **空** | log-only，不真寄 |
|
||
| **Mailpit / Mailgun** | 真走 SMTP 投遞 |
|
||
|
||
### 前後端串不起來？檢查這幾項
|
||
|
||
1. **gateway 有在跑** `ss -tlnp | grep 8888`；沒有就 `go run . -f etc/gateway.yaml`
|
||
2. **Mongo URI 有帳密**（`export MONGO_URI=...`；沒帶會查不到 seed）
|
||
3. **Redis 有密碼**（`export REDIS_PASSWORD=...`；沒帶 monc 回 `NOAUTH` → API 500）
|
||
4. **已跑 migrate**（`make migrate-up`，seed `admin@haixun.local`）
|
||
5. **FE 切到 live**：設定 → 資料來源 → Live（預設是 **mock**，根本不會打後端）
|
||
6. **API base**：`apps/web/.env` 建議 `VITE_API_BASE=`（空），走 Vite proxy `/api` → `:8888`
|
||
遠端開 `*.30cm.net` 時**不要**寫死 `http://127.0.0.1:8888`（那會打到使用者自己電腦）
|
||
7. 切 live 後**重新登入** seed：`admin@haixun.local` / `admin123`
|
||
|
||
| 資料 | 存哪 | 關機 |
|
||
|------|------|------|
|
||
| 會員 / settings | **Mongo**（monc） | 保留 |
|
||
| refresh token / 驗證碼 | **Mongo**（TTL index） | 保留（過期自動清） |
|
||
| monc 實體快取 | Redis（CacheRedis） | 可丟，會從 Mongo 回填 |
|
||
|
||
## 目錄
|
||
|
||
```text
|
||
generate/api/ # goctl 契約
|
||
generate/database/mongo # golang-migrate JSON
|
||
generate/goctl/ # handler 模板（102000）
|
||
cmd/worker/ # 獨立 worker
|
||
internal/handler|logic # goctl 產 / 薄邏輯
|
||
internal/module/ # domain · repository · usecase
|
||
internal/lib/mongo # monc URI 小工具
|
||
etc/gateway.yaml # 唯一設定
|
||
```
|
||
|
||
## 設定摘要
|
||
|
||
```yaml
|
||
CacheRedis: # monc Redis 快取
|
||
- Host: 127.0.0.1:6379
|
||
Type: node
|
||
Mongo:
|
||
URI: "mongodb://127.0.0.1:27017" # 有 auth 用 MONGO_URI 覆寫
|
||
Database: "haixun"
|
||
```
|
||
|
||
### 會員 uid
|
||
|
||
- 從 **1_000_000** 起（seed admin = `1000000`）
|
||
- 顯示補成 **8 位**：`01000000`（`%08d` / FE `padStart(8,"0")`）
|
||
- 新註冊：`1000001`, `1000002`, …
|