realvco Docs

Magic Token 機制說明

這篇講哪一個 Magic Token？

realvco 體系裡其實有兩種「Magic Link / Token」，常常被搞混：

名稱用途機制這篇講嗎
mVPS Admin Panel Magic Token點 Email 連結進自家 mVPS 上的 管理儀表板URL 帶 #token=xxx + 30 天 Cookie✅ 這篇
realvco.com 帳戶 Magic Link登入 realvco.com 帳戶頁httpOnly Cookie + CSRF 保護❌ 請看 account/login

簡單記法：「進你自己的主機」用第一種、「進 realvco 官網」用第二種。

什麼是 Magic Token？

Magic Token 是 realvco mVPS 使用的簡化登入機制。傳統帳號密碼要記一堆資訊，Magic Token 只要點一個連結就能登入。

運作原理

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  你的郵件   │────>│  Magic Link │────>│  自動登入   │
│  中的連結   │     │  (含 Token) │     │  完成       │
└─────────────┘     └─────────────┘     └─────────────┘

當你點開郵件中的 Magic Link 時：

  1. 瀏覽器開啟連結 — 網址中包含一次性或短期的認證 Token
  2. 系統驗證 Token — 確認 Token 有效且未過期
  3. 建立 Session — 自動登入並把憑證放進 Cookie，瀏覽器關掉再開仍記得你（技術上是 httpOnly Cookie，網頁上的 JavaScript 無法讀取，可避免被植入腳本盜取）
  4. 後續自動登入 — 只要 Cookie 沒過期，下次再打開網頁就自動登入

Token 類型

Realvco 使用兩種 Token：

Token 類型用途有效期
Magic Link Token首次登入24 小時
Session Token持續登入狀態30 天
  • 出現在安裝完成通知郵件中
  • 內嵌在 管理儀表板（Admin Panel） 和 AI 夥伴的存取網址
  • 一次性使用，使用後即失效
  • 24 小時後過期

Session Token

  • 成功登入後自動儲存在瀏覽器
  • 之後直接打開網址就會自動登入
  • 30 天沒用就會過期
  • 清除瀏覽器資料後要重新用 Magic Link 登入

安全考量

一個連結就能登入，不會被盜嗎？

這是大家最常問的疑慮。其實有多重保護：

安全機制說明
HTTPS 加密所有連結都使用 HTTPS，Token 在傳輸過程中加密
Token 不可預測使用加密安全的隨機生成，無法被猜測
短期有效Magic Link 24 小時後自動失效
一次性使用使用後立即失效，無法重複使用
IP 限制Token 綁定首次使用的 IP 段，降低被盜用風險

重要提醒：

  • 不要分享你的 Magic Link 給不信任的人
  • 不要公開貼（例如貼在論壇、GitHub）
  • 定期檢查 管理儀表板 中的登入紀錄
  • 如果懷疑洩漏，立即重新部署容器產生新的 Token

常見問題

A: 有兩種方式可以重新取得：

  1. 從管理儀表板複製：登入管理儀表板後，可以複製各容器的 Magic Link
  2. 聯繫客服：提供購買證明，客服會重新發送安裝郵件

Q: 可以在多個裝置使用嗎？

A: 可以。Magic Link 可以在多個裝置使用，每個裝置會建立獨立的 Session Token。

Q: 清除瀏覽器資料後怎麼辦？

A: 要重新用原始的 Magic Link 登入。建議把安裝郵件存到安全的地方。

Q: 如何登出？

A: 目前沒有主動登出按鈕。如果要強制登出，可以：

  1. 清除瀏覽器的 Cookie（瀏覽器設定 → 隱私 → 清除特定網站的資料 → 輸入你的主機網址）
  2. 或者重新部署容器（會產生新的 Token，舊的全部失效）

Cookie 是 httpOnly，意思是只能透過瀏覽器設定清掉，無法用網頁上的 JavaScript 自助清。這是刻意的安全設計（防止惡意腳本偷你的登入狀態），但代價是不能做「按一下就登出」的按鈕。如果你不確定怎麼操作瀏覽器設定，最簡單的方式是用方法 2 重新部署容器，整個 Token 池會被換新，舊的全部失效。

技術細節（給好奇的人）

Token 使用 JWT (JSON Web Token) 格式，包含以下資訊：

Header: { "alg": "HS256", "typ": "JWT" }
Payload: {
  "sub": "container_id",
  "iat": 1234567890,
  "exp": 1234654290,
  "role": "admin"
}
Signature: HMACSHA256(base64(header) + "." + base64(payload), secret)

Token 在主機端驗證，確保不被偽造。

相關文件