私人管理
IMAGE WORKSPACE
圖片總覽
上傳、管理與分享圖片，所有連結都可一鍵複製。
UPLOAD / 上傳
加入新圖片
支援 JPEG、PNG、WebP、AVIF、GIF、ICO。正在讀取單張上限…
拖放圖片至此，或點擊選擇檔案也可以直接貼上剪貼簿中的圖片
待上傳圖片檢查檔案、儲存位置與轉換選項後，再確認上傳。
READY / 可分享
上傳完成，複製需要的格式
RECENT / 最近
已上傳圖片
依圖片比例預覽，點擊圖片可放大並複製地址。
STORAGE / 節點
儲存節點
可新增或修改本機、FTP、FTPS、SFTP 節點。連線資料只保存在私人設定檔。
SYSTEM / 環境
主機資訊
顯示這次請求實際使用的 PHP 與 Web 伺服器環境，不公開設定檔或憑證。
- 載入中
- 正在讀取主機資訊…
API Token
可隨時新增或撤銷。每個新 Token 只顯示一次，請在建立後複製保存。
新 Token：現在複製保存
GUIDE / 使用說明
從第一張圖片，到自動化上傳
日常操作、API 認證與呼叫範例，都可以在這裡查閱。
日常使用
加入圖片
先設定儲存節點、日期目錄與 WebP 選項。啟用「自動上傳」時，選檔、拖放與貼上立即送出；關閉時加入待上傳清單，再確認上傳。
預覽與分享
點擊圖片卡片可放大預覽，並複製直連、Markdown、HTML 或 BBCode。「前往圖片」會直接開啟原圖網址。
整理與管理
圖片庫可搜尋檔名、選取本頁及批量刪除。設定頁可修改帳號、大小上限、儲存節點、預設目錄、SMTP 和 Token。
節點與公開圖片網址
每次上傳可選本機、FTP/FTPS 或 SFTP；設為預設位置後，新上傳會使用該節點。本機網址為網站根網址加 /uploads/，遠端網址為節點設定的完整公開目錄網址加圖片 key。
例如遠端公開目錄填 https://cdn.example.com/images，圖片網址會包含 /images/2026/10/03/檔名.webp。遠端磁碟目錄和公開網址分別設定。FTP/SFTP 節點也需要對應的 HTTPS 靜態圖片服務。
日期目錄、上傳大小與 WebP
目錄預設為 {YYYY}/{MM}/{DD}，使用 UTC 日期；可改成 photos/{YYYY}/{MM}/{DD}，最多六層。修改預設只影響新圖片。
單張上限可在設定調整為 1–512 MiB，實際上限還取 PHP 和 Web 伺服器允許的較小值。原圖與轉換結果都受限制。
WebP 品質為 0–100，預設 82。高品質通常更清晰、檔案也可能更大。轉換最多 1200 萬像素；動態 GIF 只保留首幀。已有 WebP 與 ICO 原樣保存；JPEG/PNG 優先使用已安裝的 cwebp 快速轉換，否則使用 GD。
帳號、郵件重設與刪除
名稱或郵箱都能登入；修改帳號需目前密碼。修改或重設密碼會使全部 API Token 與其他登入失效，需要重新建立 Token。
SMTP 可稍後啟用，寄送測試信成功後才儲存。未啟用時沒有郵件重設入口。圖片刪除會移除原檔，公開快取可能再顯示最多 300 秒；刪除失敗會保留記錄供排程重試。
把圖片上傳接進你的工具
先到設定建立 Token，再以 Bearer 認證呼叫本站接口。下面的範例只含佔位文字，請換成你自己的 Token。
本站 API 入口
- 目前有效單張上限
- 讀取中…
- 預設儲存節點
- 讀取中…
- 預設日期目錄
- 讀取中…
Authorization: Bearer YOUR_API_TOKEN
Token 可以列出、上傳及刪除圖片，也能讀取可用儲存位置。Bearer 圖片請求不需要 CSRF。Token 原文只在建立時顯示；遺失後可隨時撤銷並新增。帳號與節點等設定需管理員 Session。
把 photo.png 換成要上傳的檔案路徑；不要把 Token 放進網址。
查看上傳成功回應（HTTP 201）
{
"success": true,
"data": {
"id": "0123456789abcdef0123456789abcdef",
"key": "2026/10/03/0123456789abcdef0123456789abcdef.webp",
"originalName": "photo.png",
"mimeType": "image/webp",
"sizeBytes": 123456,
"backend": "local",
"url": "https://你的網域/uploads/2026/10/03/0123456789abcdef0123456789abcdef.webp",
"sha256": "檔案的 SHA-256",
"createdAt": "2026-10-03T00:00:00Z",
"status": "ready"
}
}此為示意回應；以實際 data.url 分享原圖，以 data.id 刪除。Markdown：；HTML：<img src="data.url" alt="圖片">；BBCode：[img]data.url[/img]。分享格式在工作台產生，API 回傳圖片資料。
讓瀏覽器也能上傳圖片
工具列按鈕開啟小視窗，支援選檔、拖放、貼上；右鍵網頁圖片選「上傳圖片至圖片工作台」即可直接上傳。可選本機或遠端節點、WebP 品質，完成後複製直連、Markdown、HTML 或 BBCode。
下載 Chrome 擴充功能- 下載並解壓縮 ZIP，確認資料夾內有
manifest.json。 - 在 Chrome 開啟
chrome://extensions，啟用「開發人員模式」，按「載入未封裝項目」，選擇剛解壓的資料夾。需要 Chrome 116 或更新版本。 - 固定擴充功能到工具列，開啟連線設定；圖床網址填本站網址，Token 從「設定 → API Token」建立後貼上，再按「授權並測試連線」。
- 啟用「自動上傳」時，選檔、拖放與貼上立即送出；關閉時加入清單，再按「確認上傳」。右鍵圖片使用已儲存的節點、目錄及品質直接上傳，不二次確認；成功或失敗時通知，在小視窗複製連結。
這是可自行載入的擴充功能，尚未發布到 Chrome Web Store。Token 只存在這台瀏覽器的擴充功能本機資料（未加密、不同步）；權限按圖床及來源圖片網站逐次授予。讀取來源圖片不帶 Token 或登入 Cookie；需要登入、重新導向、blob/data 網址的圖片請先另存或複製再貼上。已交給背景的工作在關閉小視窗後仍會繼續；尚未提交的待選圖片會清空。通知被系統停用時，可查看工具列徽章與最近上傳。一般網頁的空白處、文字或連結按右鍵也有「上傳圖片至圖片工作台」，點選後開啟小視窗，再選檔或貼上；對圖片本身點選則直接上傳。
圖片 API
以下接口支援 Bearer Token 或管理員 Session。JSON 請求需 Content-Type: application/json；multipart 上傳由客戶端自動設定 boundary。
POST?action=images上傳圖片
| 欄位 | 必填 | 說明 |
|---|---|---|
file | 是 | 單一檔案，支援 JPEG、PNG、WebP、AVIF、GIF、ICO，伺服器驗證檔案內容。 |
storage_id | 否 | 已設定的節點 ID；略過即使用預設節點。以 GET storage 查詢。 |
convert_webp | 否 | 1 轉 WebP；其他值不轉。WebP 與 ICO 保留原檔。 |
webp_quality | 否 | 整數 0–100，預設 82。 |
directory_template | 否 | 覆寫這次目錄；只允許英數字、底線、連字號及 {YYYY}/{MM}/{DD}，最多六層。 |
一次請求只送一張圖片；多張請逐張呼叫。成功回 HTTP 201 與圖片資料。
GET?action=storage可用儲存位置
回傳 options（id、label、driver、publicUrl）、defaultStorage、directoryTemplate、effectiveUploadBytes、maxUploadMb、webpAvailable 與 gdWebp。不回傳儲存帳密。設定節點時的完整公開目錄網址會出現在圖片直連中。
GET?action=images圖片列表與統計
limit 為 1–100，預設 24；search 搜尋檔名，最多 120 bytes；cursor 使用上一頁回傳的 nextCursor。回應包含 images、nextCursor 與 summary（imageCount、totalBytes、todayUploads）。nextCursor 為 null 時沒有下一頁。列表只顯示 ready 圖片，按建立時間及 ID 由新至舊排列。
POST?action=delete&id=<圖片ID>刪除一張圖片
成功回 {"success":true,"data":{"deleted":true}}。刪除後公開快取可能保留最多 300 秒。
POST?action=batch-delete批量刪除圖片
JSON {"ids":["圖片ID", "..."]}，一次 1–100 個不同 ID。HTTP 200 仍可能有部分失敗，請逐筆檢查 data.deleted 與 data.failed；failed 內含 id 與 message。
SESSION管理與登入接口
管理設定只接受登入 Session。先 GET ?action=session 取得 Cookie 和 csrf，以 X-CSRF-Token 呼叫 login；登入成功後保存更新的 Cookie 與 csrf。後續非 GET 請求都帶 Cookie 和 CSRF。瀏覽器管理介面必須與 API 同源。
| 方法 | action | 用途與請求 |
|---|---|---|
| GET | session | 讀取登入狀態、csrf 與 passwordResetAvailable；可於登入前呼叫。 |
| POST | login | {"identifier":"名稱或郵箱","password":"密碼"}；需登入前取得的 CSRF，成功後使用新 Cookie 與 csrf。 |
| POST | logout | 登出目前 Session。 |
| POST | request-reset | {}；需 CSRF，SMTP 啟用時寄重設信；回應訊息一律相同。 |
| POST | reset-password | {"token":"郵件中的重設 Token","password":"新密碼"}；需 CSRF。 |
| GET | account | 讀取管理員名稱與郵箱。 |
| POST | account | {"name":"名稱","email":"[email protected]","currentPassword":"目前密碼","newPassword":""}；新密碼留空不變。 |
| GET | api-tokens | 列出 Token ID、名稱與建立日期；不回傳 Token 原文或雜湊。 |
| POST | api-tokens | {"label":"自動上傳"}；201 回應含新 Token，原文僅此一次。最多 20 個。 |
| POST | revoke-token | {"id":"Token ID"}；立即撤銷。 |
| GET | nodes | 列出節點 ID、名稱、主機、目錄與公開網址；不回傳密碼或私鑰。 |
| POST | nodes | name、driver（sftp/ftp）、host、port、user、password、path、publicUrl；SFTP 加 fingerprint，可選 keyPath/keyPassphrase；FTP 可選 protocol（預設 ftps）、caFile，明文 FTP 需 insecureAck:true。 |
| PUT | nodes&id=<節點ID> | 只送要修改的欄位；密碼、私鑰、CA 留空沿用。syncExistingUrls:true 同步修正既有直連；有圖片時不可修改主機、埠及遠端目錄。 |
| POST | storage | {"defaultStorage":"節點ID"}；只修改新上傳的預設位置。 |
| POST | directory | {"template":"photos/{YYYY}/{MM}/{DD}"}；只修改新上傳的預設目錄。 |
| POST | upload-limit | {"maxUploadMb":25}；設定範圍 1–512 MiB，仍受 PHP 與 Web 伺服器限制。 |
| GET | host-info | 管理員可見的 Web 伺服器、PHP、資料庫及擴充狀態；不提供完整 phpinfo。 |
| GET | smtp | 讀取 SMTP 狀態與非敏感欄位。 |
| POST | smtp | {"enabled":false} 停用；啟用時送 enabled、host、port、user、password、encryption（tls/ssl）、fromEmail、fromName、caFile。測試信成功後儲存，密碼留空沿用。 |
session、login、request-reset、reset-password 可在未登入時使用；登出需 CSRF。其他列出的管理接口需要已登入管理員。這些接口不能只用 Bearer Token 修改設定。
回應與排查
成功回 {"success":true,"data":...}；失敗回 {"success":false,"error":{"code":"...","message":"..."}}。同時檢查 HTTP 狀態和 success 欄位。
| 狀態 | 代表什麼 | 如何處理 |
|---|---|---|
| 400 | 參數或 JSON 無效 | 按 error.message 檢查欄位、品質、節點或目錄格式。 |
| 401 / 403 | 認證或安全驗證失敗 | 檢查 Bearer Token 是否已撤銷；Session 請求重新取得登入狀態及 csrf。 |
| 404 / 409 | 操作不存在或狀態衝突 | 核對 action、圖片 ID；節點有圖片時不能修改其主機、埠與遠端目錄。 |
| 413 | 超過上傳限制 | 查詢 storage 的 effectiveUploadBytes，並核對 PHP、Nginx 的請求上限。 |
| 415 / 422 | 格式不支援或無法轉換 | 檢查原始檔案；轉換時核對 1200 萬像素限制與 GD/cwebp 支援。 |
| 429 | 登入限速 | 等待一分鐘再試；不要無限重送。 |
| 500 / 503 | 伺服器或執行環境問題 | 以回應錯誤編號查私有 PHP 日誌。SESSION_UNAVAILABLE 檢查 Session 儲存；CONFIG_PERMISSIONS 檢查設定檔權限 0600。 |
為什麼外部網頁的 fetch 不能呼叫？
目前 API 供同源管理介面及外部伺服器工具使用，未提供跨站瀏覽器 CORS 授權。外部串接請使用 cURL、Node.js 或 Python 等伺服器客戶端，避免在公開前端嵌入 API Token。
為什麼上傳成功後圖片網址仍開不了？
先確認節點的完整公開目錄網址與 HTTPS 靜態服務映射一致，例如是否缺少 /images。SFTP/FTP 只處理檔案傳輸。使用 API 回傳的 data.url，不要自行由磁碟路徑推算網址。
為什麼修改密碼後原本 Token 不能用？
修改或重設管理員密碼會撤銷全部 Token。重新登入設定頁，建立新 Token 並更新使用中的工具。Token 原文無法從後台再次取出，可隨時新增與撤銷。
