Người dùng, Vai trò & Quyền

SnapOtter được cung cấp sẵn ba vai trò tích hợp, 17 quyền chi tiết, và hỗ trợ vai trò tùy chỉnh với kiểm soát truy cập theo từng công cụ tùy chọn. Trang này bao quát toàn bộ mô hình phân quyền, phạm vi khóa API, quản lý nhóm và ghi nhật ký kiểm toán.

Các trang liên quan

OIDC / SSO | SAML SSO | Cấp phát SCIM | Bảo mật & Gia cố

Người dùng

Tạo người dùng

Quản trị viên có thể tạo người dùng qua bảng điều khiển quản trị hoặc endpoint POST /api/auth/register. Mỗi người dùng có một tên đăng nhập, vai trò, phân bổ nhóm, và một địa chỉ email tùy chọn.

Admin mặc định

Ở lần khởi động đầu tiên, SnapOtter tạo một tài khoản admin mặc định. Thông tin đăng nhập đến từ các biến môi trường:

Biến	Mặc định	Mô tả
`DEFAULT_USERNAME`	`admin`	Tên đăng nhập cho tài khoản admin ban đầu
`DEFAULT_PASSWORD`	`admin`	Mật khẩu cho tài khoản admin ban đầu

Admin mặc định buộc phải đổi mật khẩu ở lần đăng nhập đầu tiên.

Nhà cung cấp xác thực

Người dùng có thể xác thực qua nhiều phương thức:

Cục bộ - tên đăng nhập và mật khẩu được lưu trong cơ sở dữ liệu SnapOtter
OIDC - bất kỳ nhà cung cấp OpenID Connect nào (xem OIDC / SSO)
SAML - các nhà cung cấp danh tính SAML 2.0 (xem SAML SSO)
SCIM - cấp phát tự động từ một nhà cung cấp danh tính (xem Cấp phát SCIM)

Tắt xác thực

Đặt AUTH_ENABLED=false để tắt hoàn toàn xác thực. Ở chế độ này, một người dùng ẩn danh giả lập với vai trò admin được dùng cho mọi yêu cầu. Không cần đăng nhập.

WARNING

Tắt xác thực cấp quyền truy cập admin đầy đủ cho bất kỳ ai có thể tiếp cận phiên bản. Chỉ dùng điều này trong các môi trường tin cậy.

Vai trò tích hợp sẵn

SnapOtter bao gồm ba vai trò tích hợp sẵn. Chúng không thể được sửa đổi hoặc xóa.

Admin

Cả 17 quyền. Toàn quyền kiểm soát phiên bản.

tools:use files:own files:all apikeys:own apikeys:all pipelines:own pipelines:all settings:read settings:write users:manage teams:manage features:manage system:health audit:read compliance:manage webhooks:manage security:manage

Editor

7 quyền. Có thể dùng mọi công cụ và quản lý mọi tệp cùng pipeline, nhưng không thể truy cập các chức năng quản trị.

tools:use files:own files:all apikeys:own pipelines:own pipelines:all settings:read

User

5 quyền. Có thể dùng công cụ và quản lý tài nguyên của chính mình.

tools:use files:own apikeys:own pipelines:own settings:read

Tham chiếu quyền

Quyền	Mô tả
`tools:use`	Dùng bất kỳ công cụ xử lý nào
`files:own`	Xem và quản lý tệp của chính mình
`files:all`	Xem và quản lý tệp của mọi người dùng
`apikeys:own`	Tạo và quản lý khóa API của chính mình
`apikeys:all`	Xem khóa API của mọi người dùng
`pipelines:own`	Tạo và quản lý pipeline của chính mình
`pipelines:all`	Xem và quản lý pipeline của mọi người dùng
`settings:read`	Xem cài đặt phiên bản
`settings:write`	Sửa đổi cài đặt phiên bản
`users:manage`	Tạo, cập nhật và xóa tài khoản người dùng
`teams:manage`	Tạo, cập nhật và xóa nhóm
`features:manage`	Cài đặt và quản lý các gói tính năng AI
`system:health`	Truy cập các endpoint kiểm tra sức khỏe và sẵn sàng
`audit:read`	Xem nhật ký kiểm toán và liệt kê vai trò
`compliance:manage`	Quản lý vòng đời GDPR và các tính năng tuân thủ
`webhooks:manage`	Cấu hình webhook đi ra
`security:manage`	Quản lý cài đặt bảo mật (danh sách IP cho phép, ép buộc SSO)

Vai trò tùy chỉnh

Quản trị viên có quyền security:manage có thể tạo vai trò tùy chỉnh qua bảng điều khiển quản trị hoặc API vai trò. Liệt kê vai trò cần quyền audit:read.

Tạo một vai trò tùy chỉnh

bash

curl -X POST http://localhost:1349/api/v1/roles \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reviewer",
    "description": "Can use tools and view all files",
    "permissions": ["tools:use", "files:own", "files:all", "settings:read"]
  }'

Tên vai trò phải dài 2-30 ký tự, chữ và số viết thường kèm dấu gạch nối và gạch dưới.

Các quyền dành riêng cho admin

Ba quyền được dành riêng cho các vai trò tích hợp sẵn và không thể được gán cho vai trò tùy chỉnh:

compliance:manage
webhooks:manage
security:manage

API vai trò từ chối bất kỳ yêu cầu nào chứa các quyền này. Chỉ vai trò admin tích hợp sẵn mới có quyền truy cập chúng.

Quyền ở cấp công cụ

Vai trò tùy chỉnh có thể tùy chọn hạn chế những công cụ mà người dùng được truy cập. Có hai chế độ:

Chế độ	Hành vi	Yêu cầu giấy phép
`category`	Hạn chế theo phương thức (image, video, audio, document, file)	Không (miễn phí)
`tool`	Hạn chế theo ID công cụ riêng lẻ	Yêu cầu tính năng doanh nghiệp `per_tool_permissions`

Khi chế độ tool được đặt nhưng tính năng doanh nghiệp không khả dụng, SnapOtter suy giảm mượt mà và cho phép truy cập mọi công cụ.

json

{
  "name": "image-only",
  "permissions": ["tools:use", "files:own"],
  "toolPermissions": {
    "mode": "category",
    "allowed": ["image"]
  }
}

Xóa một vai trò tùy chỉnh

Khi một vai trò tùy chỉnh bị xóa, mọi người dùng được gán vai trò đó tự động được gán lại về vai trò user.

Nhóm

Nhóm gom người dùng lại để quản lý lưu trữ và lưu giữ. Một nhóm Default được tạo ở lần khởi động đầu tiên.

Trường	Kiểu	Mô tả
`name`	string	Tên nhóm duy nhất (1-50 ký tự)
`storageQuota`	number	Giới hạn lưu trữ mỗi nhóm tính bằng byte (hoạt động không cần doanh nghiệp)
`retentionHours`	number	Tự xóa đầu ra sau bấy nhiêu giờ (yêu cầu `team_retention_overrides`, doanh nghiệp)
`legalHold`	boolean	Ngăn việc tự động xóa tệp của thành viên nhóm (yêu cầu `legal_hold`, doanh nghiệp)

INFO

Nhóm Default không thể bị xóa. Các nhóm vẫn còn thành viên không thể bị xóa. Hãy gán lại thành viên trước.

Khóa API

Người dùng có thể tạo khóa API để truy cập theo lập trình. Mỗi khóa dùng tiền tố si_ và chỉ được hiển thị một lần tại thời điểm tạo.

Quyền có phạm vi

Khóa API có thể tùy chọn mang một mảng permissions. Khi được đặt, quyền hiệu lực cho một yêu cầu là giao của quyền vai trò của người dùng và quyền có phạm vi của khóa. Điều này có nghĩa một khóa API không bao giờ có thể leo thang vượt quá quyền của chính người dùng.

bash

curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline key",
    "permissions": ["tools:use", "files:own"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Hết hạn

Khóa chấp nhận một dấu thời gian expiresAt tùy chọn. Các khóa hết hạn bị từ chối tại thời điểm xác thực.

Nhật ký kiểm toán

SnapOtter ghi lại các sự kiện liên quan đến bảo mật trong một nhật ký kiểm toán có cấu trúc, được lưu trong bảng cơ sở dữ liệu audit_log.

Xem nhật ký kiểm toán

GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z

Yêu cầu quyền audit:read. Hỗ trợ phân trang (page, limit) và bộ lọc (action, ip, from, to).

Kiểm toán thao tác công cụ

WARNING

Sự kiện TOOL_EXECUTED không được ghi lại theo mặc định. Chúng là tùy chọn bật qua một trong hai đường:

Đặt cài đặt admin auditToolOperations thành true.
Giữ một giấy phép còn hiệu lực với tính năng audit_export (khả dụng ở cả gói team và enterprise).

Nếu không có một trong hai thứ này, các lần thực thi công cụ riêng lẻ không được ghi vào nhật ký kiểm toán.

Xuất

GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z

Yêu cầu quyền audit:read và tính năng doanh nghiệp audit_export (khả dụng ở cả gói team và enterprise). Hỗ trợ định dạng CSV và JSON, được lọc theo action, actorId, targetType, targetId, from, và to.

Ký chống giả mạo

Khi được bật, mỗi mục nhật ký kiểm toán được ký bằng một HMAC dẫn xuất từ DATA_ENCRYPTION_KEY. Điều này yêu cầu:

Đặt DATA_ENCRYPTION_KEY trong môi trường của bạn.
Bật cài đặt admin tamperResistantAudit.
Một giấy phép doanh nghiệp với tính năng tamper_resistant_audit.

Lưu giữ

Đặt AUDIT_RETENTION_DAYS để tự động dọn sạch các mục cũ. Mặc định là 0, nghĩa là các mục được giữ vô thời hạn.

Tham chiếu sự kiện

Sự kiện	Danh mục
`LOGIN_SUCCESS`, `LOGIN_FAILED`	Xác thực
`OIDC_LOGIN_SUCCESS`, `OIDC_LOGIN_FAILED`	Xác thực
`SAML_LOGIN_SUCCESS`, `SAML_LOGIN_FAILED`	Xác thực
`LOGOUT`	Xác thực
`USER_CREATED`, `USER_UPDATED`, `USER_DELETED`	Quản lý người dùng
`PASSWORD_CHANGED`, `PASSWORD_RESET`	Quản lý người dùng
`MFA_ENROLLED`, `MFA_DISABLED`, `MFA_VERIFIED`, `MFA_VERIFY_FAILED`	MFA
`MFA_CHALLENGE_ISSUED`, `MFA_RECOVERY_USED`, `MFA_RESET`	MFA
`ROLE_CREATED`, `ROLE_UPDATED`, `ROLE_DELETED`	Vai trò
`API_KEY_CREATED`, `API_KEY_DELETED`	Khóa API
`SETTINGS_UPDATED`, `IP_ALLOWLIST_UPDATED`	Cài đặt
`FILE_UPLOADED`, `FILE_DELETED`	Tệp
`TOOL_EXECUTED`	Công cụ (tùy chọn bật)
`SCIM_USER_PROVISIONED`, `SCIM_USER_UPDATED`, `SCIM_USER_DEPROVISIONED`	SCIM
`SCIM_GROUP_SYNCED`	SCIM
`LEGAL_HOLD_APPLIED`, `LEGAL_HOLD_RELEASED`	Tuân thủ
`GDPR_EXPORT_INITIATED`, `GDPR_USER_PURGED`, `GDPR_TEAM_PURGED`	Tuân thủ
`CONFIG_EXPORTED`, `CONFIG_IMPORTED`	Cấu hình

Quản lý phiên

Các phiên dựa trên cookie, được kiểm soát bởi SESSION_DURATION_HOURS (mặc định: 168 giờ / 7 ngày).

Thay đổi vai trò làm mất hiệu lực phiên

Khi một admin thay đổi vai trò của một người dùng, mọi phiên đang hoạt động của người dùng đó bị xóa. Người dùng phải đăng nhập lại để nhận quyền mới của mình.

Cơ chế an toàn

Bảo vệ admin cuối cùng: admin còn lại cuối cùng không thể bị hạ xuống vai trò thấp hơn. API trả về lỗi nếu bạn thử.
Ngăn tự xóa: admin không thể xóa tài khoản của chính mình qua API.

Essentials

Optimization

Adjustments

Watermark & Overlay

Utilities

Layout

Format

AI Tools

Người dùng, Vai trò & Quyền

Người dùng

Tạo người dùng

Admin mặc định

Nhà cung cấp xác thực

Tắt xác thực

Vai trò tích hợp sẵn

Admin

Editor

User

Tham chiếu quyền

Vai trò tùy chỉnh

Tạo một vai trò tùy chỉnh

Các quyền dành riêng cho admin

Quyền ở cấp công cụ

Xóa một vai trò tùy chỉnh

Nhóm

Khóa API

Quyền có phạm vi

Hết hạn

Nhật ký kiểm toán

Xem nhật ký kiểm toán

Kiểm toán thao tác công cụ

Xuất

Ký chống giả mạo

Lưu giữ

Tham chiếu sự kiện

Quản lý phiên

Thay đổi vai trò làm mất hiệu lực phiên

Cơ chế an toàn

Người dùng, Vai trò & Quyền ​

Người dùng ​

Tạo người dùng ​

Admin mặc định ​

Nhà cung cấp xác thực ​

Tắt xác thực ​

Vai trò tích hợp sẵn ​

Admin ​

Editor ​

User ​

Tham chiếu quyền ​

Vai trò tùy chỉnh ​

Tạo một vai trò tùy chỉnh ​

Các quyền dành riêng cho admin ​

Quyền ở cấp công cụ ​

Xóa một vai trò tùy chỉnh ​

Nhóm ​

Khóa API ​

Quyền có phạm vi ​

Hết hạn ​

Nhật ký kiểm toán ​

Xem nhật ký kiểm toán ​

Kiểm toán thao tác công cụ ​

Xuất ​

Ký chống giả mạo ​

Lưu giữ ​

Tham chiếu sự kiện ​

Quản lý phiên ​

Thay đổi vai trò làm mất hiệu lực phiên ​

Cơ chế an toàn ​

Người dùng, Vai trò & Quyền

Người dùng

Tạo người dùng

Admin mặc định

Nhà cung cấp xác thực

Tắt xác thực

Vai trò tích hợp sẵn

Admin

Editor

User

Tham chiếu quyền

Vai trò tùy chỉnh

Tạo một vai trò tùy chỉnh

Các quyền dành riêng cho admin

Quyền ở cấp công cụ

Xóa một vai trò tùy chỉnh

Nhóm

Khóa API

Quyền có phạm vi

Hết hạn

Nhật ký kiểm toán

Xem nhật ký kiểm toán

Kiểm toán thao tác công cụ

Xuất

Ký chống giả mạo

Lưu giữ

Tham chiếu sự kiện

Quản lý phiên

Thay đổi vai trò làm mất hiệu lực phiên

Cơ chế an toàn