ENVIRONMENT_CONFIG.md — Ma Trận Biến Môi Trường Thế Giới Keycap
Tài liệu đặc tả toàn bộ biến môi trường, thông tin kết nối và chính sách bảo mật cho thegioikeycap.vn.
1. Nguồn Sự Thật Cấu Hình
| Tầng cấu hình |
File nguồn |
Quyền hạn |
Mục đích |
| Biến môi trường toàn hệ thống |
/srv/thegioikeycap.vn/.env |
chmod 600, www-data:www-data |
Source of truth duy nhất cho MySQL root, Cloudflare, Brevo, Pancake POS, Google SA |
| Symlink tương thích Docker |
/srv/thegioikeycap.vn/docker/.env |
Symlink ../.env |
Nạp tự động vào docker compose (MYSQL_ROOT_PASSWORD) |
| Symlink script vận hành cũ |
/srv/thegioikeycap.vn/.secrets.env |
Symlink .env |
Tương thích ngược với các script shell gọi source .secrets.env |
| File mẫu cho Dev/AI |
/srv/thegioikeycap.vn/.env.example |
chmod 644, tracked in Git |
Bản mẫu cấu trúc, 100% không chứa secret thật |
| WordPress Constants |
/srv/thegioikeycap.vn/www/wp-config.php |
chmod 600, không commit |
Khởi tạo hằng số WordPress, DB user/pass, Meta CAPI token, Turnstile |
2. Bảng Danh Mục Biến Môi Trường (.env)
| Biến môi trường |
Module / Dịch vụ sử dụng |
Bắt buộc |
Mục đích & Ghi chú |
MYSQL_ROOT_PASSWORD |
Docker (keycap_mysql) |
Có |
Mật khẩu quản trị root của MySQL 8.4 container |
CF_ACCOUNT_ID |
Cloudflare API |
Có |
ID tài khoản Cloudflare quản lý DNS tên miền thegioikeycap.vn |
CF_TOKEN |
Cloudflare DNS / Turnstile |
Có |
API Token có quyền ghi Zone DNS (SPF, DKIM Brevo) |
BREVO_API |
FluentSMTP / Brevo API v3 |
Có |
Key gửi email giao dịch (xác nhận đơn, đổi mật khẩu) |
BREVO_SMTP_KEY |
SMTP Relay dự phòng |
Không |
Key kết nối SMTP truyền thống (hiện FluentSMTP dùng HTTP API v3) |
PANCAKE_SHOP_ID |
Pancake POS |
Có |
ID cửa hàng 100240306 trên POS Pancake |
PANCAKE_API_KEY |
Pancake POS Open API |
Có |
API Key đọc/ghi đơn hàng, tồn kho qua POS API |
ALLINGO_TEST_SECRET |
AllinGo API |
Không |
Secret môi trường sandbox AllinGo (dự phòng) |
ALLINGO_LIVE_SECRET |
AllinGo API |
Không |
Secret môi trường live AllinGo (dự phòng) |
ALLINGO_TEST_APP_ID |
AllinGo API |
Không |
App ID môi trường sandbox AllinGo |
ALLINGO_LIVE_APP_ID |
AllinGo API |
Không |
App ID môi trường live AllinGo |
GOOGLE_SHEETS_SA_KEY_BASE64 |
Python Scripts |
Không |
Chuỗi JSON Google Service Account mã hóa base64 |
3. Bảng Hằng Số WordPress (wp-config.php)
| Hằng số |
File / Hook đọc |
Mục đích & Quy tắc |
DB_NAME |
WordPress Core |
Tên database MySQL: thegioikeycap |
DB_USER |
WordPress Core |
User MySQL: thegioikeycap |
DB_PASSWORD |
WordPress Core |
Mật khẩu MySQL app user |
DB_HOST |
WordPress Core |
Tên host container: mysql |
TGK_PIXEL_ID |
tgk-tracking plugin |
Meta Pixel ID phục vụ Web Event Tracking |
TGK_CAPI_TOKEN |
tgk-tracking plugin |
Meta Graph API Access Token gửi Conversions API server-side |
TGK_TURNSTILE_SITE_KEY |
inc/site-config.php, theme |
Cloudflare Turnstile Public Site Key nhúng vào form login/register |
TGK_TURNSTILE_SECRET |
inc/site-config.php, theme |
Cloudflare Turnstile Secret Key verify token phía server |
DISABLE_WP_CRON |
WordPress Core |
Đặt true — giải phóng HTTP worker, nhường cron cho systemd/crontab |
4. Quy Tắc Bảo Mật Bắt Buộc
- Tuyệt đối không commit file chứa secret thật: Mọi file
.env, .secrets.env, docker/.env, wp-config.php đã được khai báo trong .gitignore.
- Phân quyền tối thiểu: File
.env luôn đặt chmod 600 và thuộc sở hữu www-data:www-data.
- Khi thêm biến mới: Bắt buộc khai báo song song biến đó vào
.env.example với giá trị placeholder mô tả để AI Agent và Dev hiểu ngữ cảnh.