LumiBaseDocs

Mặc định an toàn và lumibase doctor --security

Dự án mới không có secret dùng chung và không có admin mặc định. lumibase doctor --security đối chiếu cấu hình của dự án với checklist production.

create-lumibase sinh ra những gì

Không template nào chứa secret. File mẫu được commit liệt kê mọi secret với giá trị rỗng. Sau đó scaffolder ghi một file cục bộ (đã gitignore) chứa giá trị CSPRNG mới, với quyền 0600. Các hàm sinh secret nằm ở packages/create-lumibase/src/secrets.ts.

TemplateFile mẫu (commit)File cục bộ (sinh ra)Khoá được sinh
nextjs.env.example.envJWT_SECRET, ENCRYPTION_KEY, LUMIBASE_ADMIN_PASSWORD
default.env.example.envJWT_SECRET, ENCRYPTION_KEY
cloudflare.dev.vars.example.dev.varsJWT_SECRET, ENCRYPTION_KEY
  • JWT_SECRET gồm 48 byte ngẫu nhiên dạng base64url (64 ký tự).
  • ENCRYPTION_KEY là base64 của 32 byte ngẫu nhiên, đúng định dạng CMS kiểm tra trong apps/cms/src/config/production.ts.
  • LUMIBASE_ADMIN_PASSWORD là chuỗi ngẫu nhiên, đạt chính sách 12+ ký tự gồm đủ bốn loại ký tự. Starter không có admin mặc định: cms:bootstrap báo lỗi nếu thiếu mật khẩu.
  • .env / .dev.vars đã tồn tại thì không bao giờ bị ghi đè, vì sinh lại ENCRYPTION_KEY sẽ khiến dữ liệu đã mã hoá không giải mã được nữa. Giá trị sinh ra không bao giờ được in ra màn hình.

Các template trước đây kèm sẵn JWT_SECRET=change-me-in-production, dev_secret_key và một mật khẩu admin cố định. Mọi dự án sinh từ đó dùng chung một khoá ký. Ai biết khoá đó đều ký được token mà CMS chấp nhận.

Các mặc định khác theo template

TemplateMặc định
nextjsdocker-compose.yml đọc JWT_SECRET và ENCRYPTION_KEY dưới dạng ${VAR:?…}, nên compose từ chối khởi động khi thiếu thay vì dùng một giá trị ai cũng biết. CORS là một origin chính xác (LUMIBASE_PUBLIC_ORIGIN). LUMIBASE_API_RATE_LIMIT và LUMIBASE_DB_RLS được đặt tường minh, kèm hướng dẫn. Mọi cổng đều bind vào 127.0.0.1. Cookie refresh giữ mặc định của CMS (HttpOnly, Secure, SameSite=Lax).
defaultHono secureHeaders với CSP chặt, allowlist CORS theo origin chính xác và từ chối *, giới hạn tần suất theo IP (LUMIBASE_API_RATE_LIMIT), và bước kiểm tra lúc khởi động báo lỗi khi JWT_SECRET ngắn hơn 32 ký tự. Postgres và Redis bind vào 127.0.0.1.
cloudflareKhông có secret trong [vars] của wrangler.toml: dùng .dev.vars khi chạy cục bộ và wrangler secret put trên production. Template cũng kèm header CSP, allowlist CORS theo origin chính xác và bước kiểm tra JWT_SECRET theo kiểu fail-closed.

lumibase doctor --security

bash
npx lumibase doctor --security               # rules for the current environment
npx lumibase doctor --security --production  # force the production checklist
npx lumibase doctor --security --json        # machine-readable report
npx lumibase doctor --security --env-file deploy/prod.env

Lệnh này đọc đúng cấu hình mà CMS sẽ chạy cùng. Nó không thực thi gì và không gọi tới server nào. Các nguồn, độ ưu tiên từ thấp đến cao:

  1. file dotenv: .env, .env.local, .dev.vars, hoặc các file chỉ định qua --env-file (phân tách bằng dấu phẩy)
  2. biến môi trường của tiến trình, chỉ lấy các tên liên quan tới LumiBase
  3. [vars] trong wrangler.toml, đồng thời chọn runtime Cloudflare
  4. các mục environment: trong docker-compose.yml / compose.yaml. ${VAR}, ${VAR:-default} và ${VAR:?error} được resolve theo nguồn 1 và 2, giống cách Compose làm.

Quy tắc production được áp dụng khi NODE_ENV hoặc LUMIBASE_ENV là production, hoặc khi truyền --production. Lệnh thoát với mã 1 nếu có bất kỳ phát hiện critical nào, ngược lại là 0. Báo cáo không bao giờ chứa giá trị secret, chỉ có tên khoá và nguồn. Phần cài đặt nằm ở packages/cli/src/security/checks.ts.

Quy tắc

Rule idMức độ (dev / production)Kiểm tra gì
jwt-secret-missingcritical / criticalchưa đặt JWT_SECRET
jwt-secret-weakcritical / criticalJWT_SECRET là giá trị mặc định đã công khai (dev_secret_key, change-me-in-production, …)
jwt-secret-shortwarning / criticalJWT_SECRET ngắn hơn 32 ký tự
encryption-key-missingwarning / criticalkhông có ENCRYPTION_KEY (hoặc ENCRYPTION_KEY_<id>)
encryption-key-weak / encryption-key-formatcritical / criticalgiá trị mặc định đã biết, hoặc không phải base64 của khoá AES 16/24/32 byte
dev-auth-enabledwarning / criticalLUMIBASE_DEV_AUTH=true (chấp nhận token dev: giả mạo)
dev-credentialwarning / criticalS3_ACCESS_KEY, S3_SECRET_KEY hoặc MEILISEARCH_API_KEY là giá trị mặc định cho dev
cors-wildcardcritical / criticalcó * trong CORS_ALLOWED_ORIGINS (response có kèm credential)
cors-unsetinfo / criticalkhông có CORS_ALLOWED_ORIGINS
cors-insecure-origin— / warningorigin http:// hoặc loopback trên production
cookie-insecureinfo / criticalREFRESH_COOKIE_SECURE=false
cookie-samesite-none / cookie-samesite-invalidinfo / warning; warningREFRESH_COOKIE_SAMESITE là None, hoặc một giá trị không hợp lệ
setup-token-offinfo / warningLUMIBASE_REQUIRE_SETUP_TOKEN chưa bật (chỉ Node/Docker)
rls-invalidcritical / criticalLUMIBASE_DB_RLS không phải off hay enforce (CMS fail-closed)
rls-no-system-urlcritical / criticalenforce mà không có DATABASE_SYSTEM_URL (lỗi khi khởi động)
rls-offinfo / warningchưa enforce RLS (chỉ Node/Docker)
rate-limit-invalid / rate-limit-disabledwarning / warningLUMIBASE_API_RATE_LIMIT không phải số nguyên, hoặc bằng 0
rate-limit-fail-open— / infoLUMIBASE_RATE_LIMIT_FAIL_CLOSED không phải true
redis-unsetinfo / criticalkhông có REDIS_URL (Node/Docker; bắt buộc trên production)
database-url-missing / database-tls— / criticalthiếu DATABASE_URL, hoặc không có sslmode=require|verify-ca|verify-full (trừ khi DATABASE_SSL_MODE=disable)
admin-password-defaultcritical / criticalLUMIBASE_ADMIN_PASSWORD / ADMIN_PASSWORD là mật khẩu mặc định đã công khai
admin-password-weakwarning / warningmật khẩu admin không đạt chính sách 12+ ký tự, đủ bốn loại ký tự
secret-in-public-envcritical / criticalbiến NEXT_PUBLIC_ / VITE_ / PUBLIC_ trông giống credential
secret-committedwarning / criticalsecret được ghi thẳng trong [vars] của wrangler.toml hoặc trong file compose

Mỗi quy tắc phản ánh đúng cách CMS xử lý biến tương ứng. Phát hiện critical là những trường hợp validateProductionConfig hoặc assertDbRlsStartup từ chối khởi động, và những cấu hình trao credential cho kẻ tấn công. Đầu file checks.ts liệt kê các file nguồn, để có thể kiểm lại quy tắc khi CMS thay đổi.

Tiêu chí nghiệm thu

Bản scaffold mới của mọi template đều qua doctor --security với không phát hiện critical nào. packages/cli/src/security/scaffold-acceptance.test.ts dùng scaffolder thật để tạo từng template vào một thư mục tạm, rồi chạy lệnh thật trên đó. Với --production, cùng bản scaffold đó vẫn liệt kê những điểm mà stack cục bộ không đáp ứng được, như TLS cho database, origin http://localhost và cổng setup-token. Không phát hiện nào liên quan đến secret.

Tài liệu liên quan

Last modified: 15/11/2026