Tham chiếu trường cấu hình
Tài liệu tham khảo đầy đủ cho mọi lĩnh vực trong config.json. Tệp này kiểm soát hành vi của sản phẩm trong thời gian chạy — giới hạn gói, thanh toán, webhook và cờ tính năng. Nó tách biệt với .env, nơi nắm giữ bí mật và hệ thống cơ sở hạ tầng.
Ví dụ khởi đầu
Đây là điểm bắt đầu được đề xuất cho hoạt động triển khai tự lưu trữ mà không được định cấu hình thanh toán. Tất cả các giới hạn được đặt thành null (không giới hạn) và tính năng thanh toán bị tắt. Thay thế [email protected] với địa chỉ của chính bạn.
quản trị viên#
Một loạt các địa chỉ email được cấp quyền truy cập quản trị viên trang web. Quản trị viên có thể truy cập các trang đặc quyền như bộ lập lịch xử lý hàng loạt và bảng điều khiển sử dụng trên toàn hệ thống.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| admins | string[] | Yêu cầu | Danh sách địa chỉ email có quyền truy cập quản trị viên. Phải khớp với email được liên kết với tài khoản Thư ký của người dùng. |
đặc trưng#
Cờ tính năng kiểm soát phần nào của giao diện người dùng sản phẩm đang hoạt động. Đối với các triển khai tự lưu trữ đơn giản, bạn có thể tắt tất cả các tính năng thanh toán và chỉ để lại cờ lập lịch nếu cần.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| subscriptionEnforcementEnabled | boolean | Yêu cầu | Khi đúng, người dùng có thể xem và nâng cấp lên gói trả phí. Khi sai, giao diện người dùng nâng cấp sẽ hiển thị phần giữ chỗ sắp thanh toán. |
| workspaceBillingEnabled | boolean | Yêu cầu | Khi đúng, các bậc thanh toán và thông tin gói sẽ xuất hiện trong cài đặt thanh bên và không gian làm việc. Đặt thành false để ẩn hoàn toàn tất cả giao diện người dùng thanh toán. |
| batchSchedulerEnabled | boolean | Yêu cầu | Khi đúng, bộ lập lịch quy trình hàng loạt đang hoạt động và quản trị viên có thể truy cập. Yêu cầu Redis và BullMQ đang chạy. |
| customMCPServerTokens | boolean | Yêu cầu | Khi sai, máy chủ MCP sẽ xác thực bằng mã thông báo OAuth/Clerk tiêu chuẩn. Khi đúng, mã thông báo API tự quản lý sẽ được sử dụng thay thế — hữu ích cho các môi trường không có sự hỗ trợ của Clerk MCP. |
giới hạn#
Một loạt các bộ giới hạn kiểm soát việc sử dụng tài nguyên. Mỗi mục có thể được gắn với một cấp thanh toán thông qua billingTier, hoặc đặt thành null để áp dụng cho tất cả người dùng bất kể gói nào. Đối với việc triển khai đơn giản không cần thanh toán, một mục nhập duy nhất có "billingTier": null là đủ. null giá trị cho giới hạn số có nghĩa là không giới hạn.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| id | string | Yêu cầu | Mã định danh duy nhất cho bộ giới hạn này (ví dụ: miễn phí, chuyên nghiệp, mặc định). |
| maxTrackableItems | number | Yêu cầu | Số lượng mục có thể theo dõi tối đa (biểu mẫu + điểm cuối API) mà người dùng có thể tạo trên mỗi không gian làm việc. |
| maxResponsesPerSurvey | number | null | Yêu cầu | Số lượng phản hồi tối đa được phép cho mỗi khảo sát/biểu mẫu. null có nghĩa là không giới hạn. |
| maxWorkspaceMembers | number | null | Yêu cầu | Số lượng thành viên tối đa trong một không gian làm việc. null có nghĩa là không giới hạn. |
| maxApiLogsPerMinute | number | Yêu cầu | Số lượng sự kiện nhật ký tối đa có thể được nhập mỗi phút cho mỗi mục có thể theo dõi. Yêu cầu vượt quá được giới hạn tỷ lệ. |
| maxApiPayloadBytes | number | Yêu cầu | Kích thước tối đa tính bằng byte của tải trọng nhật ký đơn. Yêu cầu lớn hơn thế này sẽ bị từ chối. |
| logRetentionDays | number | Yêu cầu | Số mục nhật ký ngày được giữ lại trước khi bị xóa. Áp dụng cho tất cả nhật ký trong cấp này. |
| maxCreatedWorkspaces | number | null | Yêu cầu | Số lượng không gian làm việc tối đa mà một người dùng có thể tạo. null có nghĩa là không giới hạn. |
| billingTier | string | null | Yêu cầu | ID cấp thanh toán mà giới hạn này áp dụng. Phải khớp với id trong mảng Billing.tiers. Đặt thành null để áp dụng giới hạn này cho tất cả người dùng bất kể gói nào. |
thanh toán#
Cấu hình thanh toán tùy chọn để tích hợp Lemon Squeezy. Nếu bạn không sử dụng gói trả phí, hãy đặt lemonSqueezyStoreId Và manageUrl ĐẾN null và rời đi tiers như một mảng trống. Giá trị id cấp được tham chiếu theo giới hạn[].billingTier — chúng phải khớp chính xác.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| lemonSqueezyStoreId | string | null | Không bắt buộc | ID cửa hàng Lemon Squeezy của bạn. Bắt buộc nếu bạn đang xử lý thanh toán thông qua Lemon Squeezy. |
| manageUrl | string | null | Không bắt buộc | URL tới trang quản lý thanh toán được hiển thị cho người dùng. Điển hình là URL cổng thông tin khách hàng Lemon Squeezy của bạn. |
billing.tiers[]
Mảng bậc thanh toán được hiển thị trong giao diện người dùng nâng cấp. Mỗi cấp phải có một id duy nhất khớp với mục nhập tương ứng trong limit[].billingTier.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| id | string | Yêu cầu | Mã định danh cấp duy nhất. Được tham chiếu bởi các giới hạn[].billingTier. |
| name | string | Yêu cầu | Tên hiển thị được hiển thị cho người dùng (ví dụ: Pro, Team). |
| priceLabel | string | Yêu cầu | Chuỗi giá hiển thị trong giao diện người dùng (ví dụ: $25). |
| priceInterval | string | Yêu cầu | Khoảng thời gian thanh toán được hiển thị bên dưới giá (ví dụ: mỗi tháng). |
| description | string | Yêu cầu | Mô tả ngắn gọn về những gì cấp độ này bao gồm. |
| tone | "neutral" | "accent" | "strong" | Yêu cầu | Chủ đề trực quan của thẻ cấp độ. giọng điệu và mạnh mẽ là phong cách nổi bật; trung lập là mặc định. |
| mostPopular | boolean | Yêu cầu | Khi đúng, hiển thị huy hiệu Phổ biến nhất trên thẻ cấp độ này. |
| lemonSqueezyVariantId | string | null | Không bắt buộc | ID biến thể sản phẩm Lemon Squeezy cho cấp độ này. Cần thiết để thanh toán hoạt động. |
| enabled | boolean | Yêu cầu | Khi sai, cấp này sẽ bị ẩn khỏi giao diện người dùng nâng cấp ngay cả khi tính năng thanh toán được bật. |
cách sử dụng#
Các biện pháp kiểm soát việc sử dụng API toàn cầu áp dụng trên tất cả không gian làm việc và người dùng.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| invalidApiKeyRateLimitPerMinute | number | Yêu cầu | Số lượng yêu cầu tối đa có khóa API không hợp lệ được phép mỗi phút trên mỗi IP trước khi nguồn bị giới hạn tốc độ. Giúp ngăn chặn việc nhồi thông tin xác thực. |
| maxBodyBytes | number | Yêu cầu | Kích thước tối đa tính bằng byte cho nội dung yêu cầu nhật ký ở cấp cổng API. Các yêu cầu vượt quá mức này sẽ bị từ chối trước khi đến lớp dịch vụ. |
| pageSize | number | Yêu cầu | Số mục nhật ký được tìm nạp trên mỗi trang khi tải trình xem nhật ký. |
webhook#
Kiểm soát hàng đợi phân phối webhook gửi đi được hỗ trợ bởi Redis và BullMQ. Giới hạn tốc độ ở đây áp dụng cho người tiêu dùng hàng đợi, không áp dụng cho việc nhập nhật ký gửi đến.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| queue.enabled | boolean | Yêu cầu | Khi đúng, các webhook gửi đi sẽ được xếp hàng đợi trong Redis và được phân phối không đồng bộ. Yêu cầu Redis phải chạy. |
| queue.rateLimitMs | number | Yêu cầu | Thời gian chờ tối thiểu là mili giây giữa các lần gửi webhook liên tiếp từ hàng đợi. |
| queue.rateLimitMax | number | Yêu cầu | Số lượng sự kiện webhook tối đa có thể được gửi trong cửa sổ rateLimitMs. |
lô#
Cấu hình cho bộ lập lịch hàng loạt nền. Bộ lập lịch cũng phải được kích hoạt thông qua features.batchSchedulerEnabled.
| Cánh đồng | Kiểu | Yêu cầu | Sự miêu tả |
|---|---|---|---|
| schedulerTimeZone | string | Yêu cầu | Chuỗi múi giờ IANA được sử dụng để lên lịch công việc hàng loạt (ví dụ: UTC, America/New_York). Ảnh hưởng khi kích hoạt công việc dựa trên cron. |