Cấu hình NextPDF Connect

Tổng quan nhanh

NextPDF Connect có hai bề mặt cấu hình. Máy chủ Model Context Protocol (MCP) đọc một tệp YAML và các biến NEXTPDF_MCP_*. Máy chủ REST và gRPC đọc các biến môi trường NEXTPDF_*. Cấu hình được cố định sau khi máy chủ khởi động.

Cài đặt

composer require nextpdf/server

Tổng quan về khái niệm

Máy chủ MCP phân giải cấu hình theo một thứ tự ưu tiên cố định. Nguồn có ưu tiên cao nhất sẽ được áp dụng:

Biến môi trường (NEXTPDF_MCP_*).
Phần nextpdf_mcp của tệp cấu hình YAML.
Giá trị mặc định tích hợp sẵn.

Truyền tệp YAML bằng --config=PATH. Nếu bỏ qua tham số này, máy chủ chỉ dùng các giá trị mặc định và biến môi trường. McpConfig được tạo ra là một value object readonly. Không thiết lập nào có thể được thay đổi sau khi khởi động.

Máy chủ REST và gRPC đọc HttpConfig từ môi trường khi khởi động. Chúng hỗ trợ NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED và NEXTPDF_CORS_ENABLED dưới dạng các ghi đè từ môi trường. Các giới hạn còn lại sử dụng giá trị mặc định an toàn.

Bề mặt API

Cấu hình MCP (`nextpdf-mcp`)

Tệp YAML, phần nextpdf_mcp:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

Ghi đè qua môi trường cho máy chủ MCP:

Biến	Khóa cấu hình	Mặc định
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	cho phép mọi công cụ
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	thư mục tạm của hệ thống + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 MB)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` giây
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(kiểm soát `parse_pdf`)	không đặt (đã tắt)
`NEXTPDF_AST_TOOLS_ENABLED`	(kiểm soát các công cụ AST)	đã bật
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(kiểm soát các công cụ mutation AST)	không đặt (đã tắt)

Cấu hình REST và gRPC

Biến	Mặc định	Tác dụng
`NEXTPDF_BIND`	`0.0.0.0:8080`	Địa chỉ lắng nghe của REST
`NEXTPDF_WORKER_COUNT`	`4`	Số lượng worker PHP của RoadRunner
`NEXTPDF_SESSIONS_ENABLED`	`false`	Bật các endpoint phiên lưu trạng thái
`NEXTPDF_CORS_ENABLED`	`false`	Bật các header CORS trong phản hồi
`NEXTPDF_API_KEYS`	không đặt	Định nghĩa khóa API nội tuyến
`NEXTPDF_API_KEYS_FILE`	không đặt	Đường dẫn đến tệp khóa API
`NEXTPDF_JOB_STORE_PATH`	thư mục tạm của hệ thống	Đường dẫn đến job store SQLite
`NEXTPDF_REDIS_HOST`	không đặt	Bật các store dựa trên Redis khi biến này được đặt

Máy chủ REST sử dụng Redis khi NEXTPDF_REDIS_HOST được đặt và ext-redis được nạp:

Biến	Mặc định
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	rỗng
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` giây
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` giây

Mã mẫu — bắt đầu nhanh

Chạy máy chủ MCP với một tệp cấu hình tường minh:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

Mã mẫu — môi trường sản xuất

Thu hẹp danh mục MCP thành một danh sách cho phép tường minh, đồng thời nâng mức rủi ro của một công cụ:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

Với enabled_tools không rỗng, chính sách bảo mật chỉ chấp nhận những tên công cụ được liệt kê. Registry loại bỏ mọi công cụ khác một cách âm thầm. Danh sách rỗng hoặc vắng mặt sẽ chấp nhận mọi công cụ khả dụng.

Trường hợp đặc biệt và điểm cần lưu ý

Không thể hạ cấp hai công cụ quan trọng. Theo thiết kế, output_pdf và sign_pdf luôn chịu kiểm soát phê duyệt: một mục risk_level_overrides hạ một trong hai công cụ xuống dưới ApprovalRequired sẽ ném ra InvalidArgumentException khi nạp, và máy chủ từ chối khởi động. Bạn có thể nâng hoặc hạ mức rủi ro của mọi công cụ khác, vì vậy hãy xem xét từng lần hạ cấp dựa trên mô hình mối đe dọa của riêng bạn. Xem /connect/hitl-risk-tiers/.
enabled_tools lọc, nó không thêm. Việc liệt kê tên một công cụ Pro khi nextpdf/premium vắng mặt cũng không làm công cụ đó xuất hiện. Danh sách cho phép là giao của danh sách đó với những công cụ mà registry thực sự phát hiện.
Biến môi trường ưu tiên hơn YAML đối với máy chủ MCP. Một biến NEXTPDF_MCP_* ghi đè khóa tương ứng trong tệp YAML. Máy chủ REST và gRPC hoàn toàn không đọc tệp YAML của MCP.
Cần bật tùy chọn cho parse_pdf. Máy chủ chỉ đăng ký công cụ parse_pdf khi NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED là true hoặc 1. Theo mặc định, nó vắng mặt, ngay cả trong danh mục core.

Hiệu năng

Cấu hình được phân tích cú pháp một lần khi khởi động. Các thiết lập max_documents và document_ttl giới hạn kho tài liệu trong bộ nhớ. Giảm các giá trị này sẽ giảm bộ nhớ đỉnh, nhưng rút ngắn vòng đời của tài liệu. Số lượng worker và các giới hạn payload theo từng bậc là các tham số điều chỉnh khi triển khai, được trình bày trong /connect/deployment/.

Lưu ý bảo mật

Hãy coi enabled_tools như một biện pháp kiểm soát từ-chối-mặc-định cho các triển khai theo nguyên tắc đặc quyền tối thiểu: chỉ liệt kê những công cụ mà từng tích hợp cần.
Không bao giờ lưu khóa API trong tệp YAML. Hãy dùng NEXTPDF_API_KEYS_FILE với một tệp được gắn dưới dạng secret của Docker hoặc Kubernetes. Máy chủ ưu tiên một file store hỗ trợ nạp lại nóng, nhờ đó các khóa được luân chuyển mà không cần khởi động lại. Xem /connect/security-and-operations/.
Thư mục temp_directory là thư mục gốc bắt buộc cho đầu ra tệp. Máy chủ chuẩn hóa các đường dẫn đầu ra và từ chối bất kỳ đường dẫn nào phân giải ra ngoài thư mục đó.

Tuân thủ

Trang này mô tả cơ chế cấu hình. Các trích dẫn về tuân thủ cho xác thực và bảo mật truyền tải nằm trong /connect/security-and-operations/.

Bối cảnh thương mại

Các giới hạn payload và timeout theo từng bậc (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit và các timeout tương ứng) áp dụng cho lớp truyền tải REST tương ứng với bậc của khóa API đã xác thực. Chúng chỉ có hiệu lực khi các công cụ Pro hoặc Enterprise được cài đặt và khóa có quyền dùng chúng.

Xem thêm

/connect/install/ — cài đặt và gói tùy chọn
/connect/boot-and-discovery/ — cách cấu hình đưa vào trình tự khởi động
/connect/hitl-risk-tiers/ — mô hình rủi ro và ghi đè chỉ-nâng-cấp
/connect/security-and-operations/ — cấu hình khóa API và bảo mật truyền tải
/connect/deployment/ — số lượng worker, Redis và các giới hạn theo bậc trong môi trường sản xuất