External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
42e1dc9799f60c7dde46b9485e5f37a5a29630ae
SnapOtter/apps/docs/vi/guide/users-roles.md
T
SnapOtterandGitHub d10d0f544f fix: release QA hardening across processing, media, security, and CI gates (#649) 
A release-readiness QA pass over the whole product. The commits split into
defects a user would hit and gates that were reporting green while measuring
nothing.

## Fixes that change behaviour

Rate limiting was bypassable on every install: TRUST_PROXY defaulted to true, so
request.ip came from a client-set header and a forged X-Forwarded-For got past
the login limiter. The default is now a private-network trust list.

A transient Postgres outage stranded in-flight jobs, leaving finished output on
disk with no row pointing at it. A reconciler now resolves those rows and adopts
the bytes rather than dropping the work.

A Redis connection that moved to a new address wedged every read-blocked
consumer, so completions stopped signalling while health still answered 200.
Socket timeouts plus subscriber pings recover it.

Installing more than one AI bundle left the shared venv multi-versioned and
silently broke three tools. The installer now reconciles distributions to one
version each.

Converting an image to JXL at quality 1 through 4 returned a 500, because
libjxl 0.7 rejects the distance those values compute. The quality is floored at
what the encoder honours. A missing ffmpeg was also reported to the user as a
corrupt upload; it now says the engine is unavailable.

RAW uploads reached an unpatched LibRaw on arm64, so it is built from source at
0.22.2, and the release scan was split so it can fail on an unfixed critical
instead of hiding it behind ignore-unfixed.

## Gates that could not fail

Two mutation lanes ran zero mutants because Stryker crawled the gitignored docs
build; coverage discarded its whole report on any failing test; the lint gate
skipped root tests, scripts, and two workspaces; and several generated matrices
counted a host missing ffmpeg as a passing tool. Each now measures what it
claims.

Full evidence and the outstanding release items are tracked locally and are not
part of this branch.
2026-07-27 15:37:30 +08:00

14 KiB
Raw Blame History

description, i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version
description i18n_source_hash i18n_provenance i18n_output_hash i18n_hash_version
Quản lý người dùng, vai trò tích hợp sẵn và tùy chỉnh, quyền, khóa API, nhóm, phiên và nhật ký kiểm toán trong SnapOtter. bea8955f3aff human efe6a520c09f 2

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.

::: tip 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 và quản lý tài khoản người dùng trong phạm vi quyền hạn của tác nhân
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ý các tính năng tuân thủ và vòng đời GDPR; hoạt động phá hoại của người dùng vẫn bị giới hạn bởi thẩm quyền
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

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.

Ranh giới quản lý được ủy quyền

Tất cả 17 quyền có thể được ủy quyền thông qua các vai trò tùy chỉnh, nhưng quyền quản trị không làm cho vai trò đó tương đương với vai trò admin tích hợp sẵn. Các đột biến người dùng được users:manage ủy quyền, các hoạt động phá hoại được compliance:manage ủy quyền và quản lý vai trò tùy chỉnh được security:manage ủy quyền đều bị giới hạn bởi quyền hạn hiện tại của tác nhân:

  • Các vai trò tích hợp theo admin > editor > user; vai trò tùy chỉnh nằm bên dưới vai trò tích hợp.
  • Các quyền của mục tiêu phải được bao gồm bởi các quyền có hiệu lực của tác nhân. Do đó, khóa API có phạm vi không thể thực hiện các quyền bị bỏ qua trong phạm vi của nó.
  • Quyền truy cập công cụ của vai trò mục tiêu phải được bao hàm bởi quyền truy cập công cụ của chính tác nhân.
  • Tài khoản bị vô hiệu hóa được kiểm tra dựa trên vai trò ban đầu khi vai trò đó được ghi là disabled:<original-role>.
  • Việc xóa vai trò tùy chỉnh cũng yêu cầu có quyền chỉ định dự phòng user tích hợp sẵn; thành viên bị khuyết tật vẫn bị vô hiệu hóa dưới dạng disabled:user.

Thông tin xác thực và cấu hình toàn cầu chặt chẽ hơn: việc phát hành hoặc thu hồi mã thông báo SCIM và nhập cấu hình phiên bản yêu cầu vai trò admin tích hợp sẵn với toàn quyền quản trị hiệu quả.

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ụ.

{
  "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.

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:

  1. Đặt cài đặt admin auditToolOperations thành true.
  2. 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:

  1. Đặt DATA_ENCRYPTION_KEY trong môi trường của bạn.
  2. Bật cài đặt admin tamperResistantAudit.
  3. 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.
Reference in New Issue View Git Blame Copy Permalink