Truy cập từ xa & bảo mật

API chạy trên cổng relay (mặc định 9900). Để server/worker bên ngoài gọi được, cấu hình địa chỉ Internet ở Cài đặt → Internet & Đám mây (dịch vụ "Nhân viên và API"), chọn một cách tạo địa chỉ:

1. Cloudflare tự động (khuyên dùng): kết nối tài khoản Cloudflare của bạn ở đầu trang → chọn tên miền + "Tên máy" → Áp dụng. Deplao tự tạo tunnel và địa chỉ cố định trên tên miền của bạn; địa chỉ hiện ở bảng dịch vụ, gọi API tại https://<địa-chỉ>/api/v1.
2. ngrok: dashboard.ngrok.com → Your Authtoken → dán vào ô Authtoken; mục Domains → lấy domain tĩnh miễn phí → dán vào ô Domain tĩnh; bật "Nhân viên và API". URL cố định: https://<domain>/api/v1.
3. Cloudflare thủ công (đã tự cấu hình tunnel): one.dash.cloudflare.com → Networks → Tunnels → tạo tunnel (Cloudflared), sao chép token dán vào ô Tunnel token; thêm Public Hostname trỏ tới http://localhost:9900; nhập địa chỉ công khai rồi bật "Nhân viên và API". Token được lưu mã hoá.
4. Địa chỉ tạm: không cần tài khoản, nhưng URL đổi mỗi lần khởi động lại, chỉ nên dùng thử.

#Khuyến nghị khi mở ra Internet

• Tạo key riêng cho từng hệ thống, scope tối thiểu, giới hạn tài khoản.
• Đặt IP được phép nếu server gọi có IP cố định (IP thật được lấy từ header tunnel).
• Webhook nhận ở phía bạn phải dùng https và kiểm tra chữ ký.
• Trang /docs và /api/v1/openapi.json mặc định ai cũng xem được (chỉ mô tả endpoint, không có dữ liệu). Muốn bắt buộc key khi xem từ xa: tắt "Tài liệu công khai" ở tab Nâng cao.
• Bật IP restriction / basic auth trên dashboard ngrok hoặc Cloudflare Access cho môi trường production.
• Lưu ý: các endpoint file của chế độ nhân viên (/api/media/*, /api/library/file|thumb/*) bắt buộc phiên đăng nhập nhân viên (token của app nhân viên, chỉ trả file của tài khoản được giao) và không nhận API key. Hệ thống bên ngoài tải file qua API v1 (vd GET /api/v1/library/items/{uuid}/file) bằng key có scope phù hợp.

#Công tắc khẩn cấp

• Công cụ → Ứng dụng, API & Webhook → API → tắt API (trả 503 ngay, không ghi log/event).
• Thu hồi tất cả key một chạm.