cpanel-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cPanel — Deploy mã nguồn

cPanel — 部署源代码

Vì toolkit gọi cPanel API từ xa (không SSH), việc đưa file lên server đi theo luồng: upload archive → giải nén trên server → di chuyển file → ghi file cấu hình.

由于工具包是远程调用cPanel API（无SSH），文件上传到服务器的流程为：上传归档文件 → 在服务器上解压 → 移动文件 → 写入配置文件。

Các lệnh thao tác file

文件操作命令

Lệnh	Mô tả
`file:upload <local> <remotedir> [overwrite]`	Upload 1 file local lên server (multipart)
`file:extract <archive> <destdir>`	Giải nén zip/tar trên server (API2 fileop)
`file:move <src> <destdir>`	Di chuyển/đổi tên file/thư mục
`file:save <dir> <file> <local_content_file>`	Ghi nội dung 1 file text (vd cấu hình)
`file:mkdir <path> <name>`	Tạo thư mục
`file:delete <path>`	Xóa file/thư mục (engine chặn nếu thiếu xác nhận; chạy lại kèm `--yes` )
`file:chmod <path> <mode>`	Đổi quyền file (octal 3-4 chữ số, vd 644/0755; cần `--yes` ) — sửa lỗi 403/500 sau restore/malware
`file:read <dir> <file>`	Đọc lại để kiểm tra

Đường dẫn server tính tương đối thư mục home (vd

public_html

public_html/blog

命令	描述
`file:upload <local> <remotedir> [overwrite]`	将本地单个文件上传到服务器（多部分上传）
`file:extract <archive> <destdir>`	在服务器上解压zip/tar文件（API2 fileop）
`file:move <src> <destdir>`	移动/重命名文件/文件夹
`file:save <dir> <file> <local_content_file>`	写入文本文件内容（例如配置文件）
`file:mkdir <path> <name>`	创建文件夹
`file:delete <path>`	删除文件/文件夹（引擎会拦截未确认的操作；需添加 `--yes` 参数重新执行）
`file:chmod <path> <mode>`	修改文件权限（3-4位八进制数，如644/0755；需添加 `--yes` 参数）——修复恢复/恶意软件清理后的403/500错误
`file:read <dir> <file>`	读取文件内容用于验证

服务器路径以主目录为相对路径（例如

public_html

、

public_html/blog

）。

Deploy WordPress trọn gói (một lệnh)

一键部署完整WordPress

bash

cpanel deploy:wp <docroot> <dbname> <dbuser> <dbpass> [table_prefix]

bash

cpanel deploy:wp <docroot> <dbname> <dbuser> <dbpass> [table_prefix]

Ví dụ: deploy vào document root chính

示例：部署到主文档根目录

cpanel deploy:wp public_html wpblog wpuser 'M@tKhau#Manh2026'


Lệnh này tự động:
1. Tải `wordpress.org/latest.zip` về máy local.
2. Upload lên `<docroot>` và giải nén trên server.
3. Di chuyển nội dung `wordpress/*` lên `<docroot>`, dọn zip + thư mục thừa.
4. Tạo database + MySQL user + cấp quyền (tự ghép tiền tố `<user>_`).
5. Lấy salt keys chính chủ từ WordPress.org và sinh `wp-config.php`.

Sau khi xong, mở website trên trình duyệt để hoàn tất bước cài đặt WordPress
(chọn ngôn ngữ, tạo tài khoản admin).

cpanel deploy:wp public_html wpblog wpuser 'M@tKhau#Manh2026'


该命令会自动执行以下操作：
1. 从`wordpress.org/latest.zip`下载到本地。
2. 上传到`<docroot>`并在服务器上解压。
3. 将`wordpress/*`的内容移动到`<docroot>`，清理多余的zip文件和文件夹。
4. 创建数据库 + MySQL用户 + 授权（自动添加`<user>_`前缀）。
5. 从WordPress.org获取专属salt密钥并生成`wp-config.php`文件。

完成后，在浏览器中打开网站以完成WordPress的安装步骤（选择语言、创建管理员账户）。

Deploy static site (HTML/CSS/JS hoặc source build sẵn)

部署静态站点（HTML/CSS/JS或已构建的源代码）

deploy:static

nén nội dung thư mục local rồi upload + giải nén — không tạo thư mục lồng, dùng được cho mọi source tĩnh hoặc đã build (React/Vue dist, Hugo, v.v.).

bash

undefined

deploy:static

会压缩本地文件夹的内容然后上传+解压——不会创建嵌套文件夹，适用于任何静态资源或已构建的项目（React/Vue dist、Hugo等）。

bash

undefined

nén & deploy cả thư mục

压缩并部署整个文件夹

cpanel deploy:static ./dist public_html/static

hoặc deploy 1 file zip có sẵn

或者部署已有的zip文件

cpanel deploy:static ./build.zip public_html/app

undefined

cpanel deploy:static ./build.zip public_html/app

undefined

Deploy PHP app + MySQL (đã kiểm chứng)

部署PHP应用+MySQL（已验证）

bash

undefined

bash

undefined

1. (tùy chọn) tạo subdomain cho app

1.（可选）为应用创建子域名

cpanel subdomain:add php thachtestvibe.dev

2. tạo database

2. 创建数据库

cpanel db:create phpapp cpanel db:user-create phpuser '<mật khẩu mạnh>' cpanel db:grant phpuser phpapp

cpanel db:create phpapp cpanel db:user-create phpuser '<强密码>' cpanel db:grant phpuser phpapp

3. deploy mã nguồn (KHÔNG kèm file secret)

3. 部署源代码（不包含机密文件）

cpanel deploy:static ./myphpapp public_html/php

4. ghi file config chứa credential TRỰC TIẾP trên server (không nằm trong zip)

4. 在服务器上直接写入包含凭证的配置文件（不在zip包中）

cpanel file:save public_html/php config.php ./local-config.php

Trong config dùng **tên DB/user đầy đủ có tiền tố** (`<user>_phpapp`), host `localhost`.

cpanel file:save public_html/php config.php ./local-config.php

配置文件中需使用**带前缀的完整数据库/用户名**（`<user>_phpapp`），主机为`localhost`。

Deploy Laravel KHÔNG cần SSH (đã kiểm chứng end-to-end)

无需SSH部署Laravel（已端到端验证）

Vì không có SSH (không chạy được

composer

artisan

trên server), công thức là build local rồi bundle:

bash

undefined

由于没有SSH（无法在服务器上运行

composer

artisan

），解决方案是本地构建后打包：

bash

undefined

=== LÀM LOCAL ===

=== 本地操作 ===

1. Tạo app + build vendor khớp PHP server (vd server PHP 8.3 → platform 8.3)

1. 创建应用并构建与服务器PHP版本匹配的vendor目录（例如服务器PHP 8.3 → 指定platform 8.3）

composer create-project laravel/laravel myapp # dùng bản Laravel còn được hỗ trợ cd myapp composer config platform.php 8.3.0 composer update --no-dev --optimize-autoloader # vendor gọn, đúng PHP target

composer create-project laravel/laravel myapp # 使用仍受支持的Laravel版本 cd myapp composer config platform.php 8.3.0 composer update --no-dev --optimize-autoloader # 精简vendor目录，匹配目标PHP版本

2. DÙNG SQLITE: pre-migrate LOCAL (khỏi chạy artisan migrate trên server)

2. 使用SQLITE：本地预迁移（无需在服务器上运行artisan migrate）

touch database/database.sqlite php artisan migrate --force php artisan optimize:clear # tránh cache path local cd ..

touch database/database.sqlite php artisan migrate --force php artisan optimize:clear # 清除本地路径缓存 cd ..

=== DEPLOY (1 lệnh) ===

=== 部署（一键命令） ===

cpanel deploy:laravel ./myapp public_html/myapp https://app.example.com


`deploy:laravel` tự: sinh `APP_KEY`, loại `.env` local khỏi zip, upload + giải nén,
ghi `.env` server (mặc định SQLite, file session/cache). Sau đó **2 bước thủ công**:

```bash

cpanel deploy:laravel ./myapp public_html/myapp https://app.example.com


`deploy:laravel`会自动生成`APP_KEY`，从zip包中移除本地`.env`文件，上传+解压，写入服务器端`.env`文件（默认使用SQLite，文件存储session/缓存）。之后需要**两步手动操作**：

```bash

Trỏ document root vào public/ + đặt PHP version cho vhost

将文档根目录指向public/并为虚拟主机设置PHP版本

cpanel subdomain:add app example.com public_html/myapp/public cpanel uapi LangPHP php_set_vhost_versions vhost=app.example.com version=alt-php83


**Điểm mấu chốt đã kiểm chứng:**
- Laravel 13 cần PHP ≥ 8.3 — `composer config platform.php` phải khớp PHP server, và
  vhost phải đặt đúng version. Tránh bản Laravel EOL (vd 10.x) vì composer 2.9 chặn do
  security advisory.
- **DB**: SQLite pre-migrated local là cách sạch nhất (không cần migrate trên server,
  không cần MySQL). File `database/database.sqlite` ghi được vì PHP chạy bằng quyền user.
  Nếu cần MySQL: tạo DB (`db:*`) + sửa `.env` (`file:save`) + chạy migrate qua cron one-shot.
- **MIME/PHP version khi verify qua userdir:** xem mục dưới — path từng-là-subdomain-docroot
  bị áp PHP account-default (vd 7.4), không phải PHP của subdomain.

cpanel subdomain:add app example.com public_html/myapp/public cpanel uapi LangPHP php_set_vhost_versions vhost=app.example.com version=alt-php83


**已验证的关键点：**
- Laravel 13需要PHP ≥ 8.3 — `composer config platform.php`必须与服务器PHP版本匹配，且虚拟主机需设置正确版本。避免使用已终止支持的Laravel版本（如10.x），因为composer 2.9会因安全提醒拦截安装。
- **数据库**：本地预迁移SQLite是最简洁的方式（无需在服务器上执行迁移，无需MySQL）。`database/database.sqlite`文件可被PHP以用户权限写入。如果需要MySQL：创建数据库（`db:*`命令）+ 修改`.env`（`file:save`命令）+ 通过一次性定时任务执行迁移。
- **验证用户目录时的MIME/PHP版本**：见下文——作为子域文档根目录的路径在通过用户目录访问时会应用**账户默认PHP版本**（如7.4），而非为子域设置的PHP版本。

Clone Git repo về hosting (đã kiểm chứng)

克隆Git仓库到主机（已验证）

bash

undefined

bash

undefined

path tương đối tự resolve thành tuyệt đối; tên repo tự suy từ basename

相对路径会自动解析为绝对路径；仓库名称自动从basename推断

cpanel git:clone https://github.com/user/repo.git myrepo cpanel git:list # xem repo + available_branches

Thư mục đích phải **CHƯA tồn tại**. Clone là async — đợi vài giây rồi `file:read`/
`list_files` để xác minh. Repo private cần URL có token.

cpanel git:clone https://github.com/user/repo.git myrepo cpanel git:list # 查看仓库及可用分支

目标文件夹必须**不存在**。克隆为异步操作——等待几秒后使用`file:read`/`list_files`验证。私有仓库需使用包含令牌的URL。

Deploy Node.js app (Passenger — đã kiểm chứng đăng ký)

部署Node.js应用（Passenger — 已验证注册）

bash

undefined

bash

undefined

1. subdomain làm Application URL

1. 创建子域名作为应用URL

cpanel subdomain:add node thachtestvibe.dev

2. đưa code vào app root (KHÁC docroot web; vd thư mục 'nodeapp')

2. 将代码放入应用根目录（与Web文档根目录不同；例如

nodeapp

文件夹）

cpanel deploy:static ./nodeapp nodeapp

3. đăng ký app (app_root, domain, app_name)

3. 注册应用（app_root, domain, app_name）

cpanel node:create nodeapp node.thachtestvibe.dev mynode app.js production cpanel node:list


> **Giới hạn không-SSH:** Passenger không chạy `npm install` qua API. Hoặc dùng app
> **zero-dependency** (chỉ module built-in của Node), hoặc bundle sẵn `node_modules`
> vào zip. App nghe qua `http.createServer().listen(process.env.PORT||3000)` —
> Passenger tự hijack. Mỗi domain chỉ gắn được **một** app.

cpanel node:create nodeapp node.thachtestvibe.dev mynode app.js production cpanel node:list


> **无SSH限制**：无法通过API让Passenger执行`npm install`。要么使用**零依赖**应用（仅使用Node内置模块），要么将`node_modules`打包到zip包中。应用需通过`http.createServer().listen(process.env.PORT||3000)`监听——Passenger会自动接管端口。每个域名只能绑定**一个**应用。

Deploy thủ công một ứng dụng bất kỳ (file ops thô)

手动部署任意应用（原始文件操作）

bash

cpanel file:upload ./myapp.zip public_html
cpanel file:extract public_html/myapp.zip public_html
cpanel file:save public_html .env ./local.env

bash

cpanel file:upload ./myapp.zip public_html
cpanel file:extract public_html/myapp.zip public_html
cpanel file:save public_html .env ./local.env

Kiểm chứng sau deploy

部署后验证

bash

undefined

bash

undefined

1. File đã vào đúng chỗ

1. 确认文件已上传到正确位置

cpanel uapi Fileman list_files dir=public_html | jq -r '.data[].file'

2. wp-config.php đúng credential

2. 确认wp-config.php的凭证正确

cpanel file:read public_html wp-config.php | jq -r .data.content

3. Database tồn tại

3. 确认数据库存在

cpanel db:list


**Xem website khi domain CHƯA trỏ DNS:** dùng URL mod_userdir của server:
`https://<server-host>/~<cpaneluser>/` (phục vụ `public_html`) hoặc
`https://<server-host>/~<cpaneluser>/<subdir>/` cho thư mục con. Đây là cách kiểm
chứng file tĩnh + PHP khi domain chưa trỏ. Lưu ý:
- File tĩnh & PHP trong `public_html/*` xem được qua userdir.
- **Node.js/Passenger và vhost subdomain KHÔNG chạy qua userdir** — cần DNS trỏ thật
  để hit đúng vhost. Khi chưa có DNS, chỉ xác minh được tới mức API trả `enabled=1`.
- Truy cập thẳng `https://<domain>/` rơi vào vhost mặc định cho tới khi DNS đúng.
- **PHP version qua userdir (CloudLinux):** thư mục là/từng-là **docroot của subdomain**
  bị áp PHP **account-default** (thường 7.4) khi truy cập qua userdir, KHÔNG theo version
  đã đặt cho subdomain. Để verify app cần PHP mới (vd Laravel/8.3) khi chưa có DNS: deploy
  vào **subdir thường dưới `public_html`** (chưa từng là subdomain docroot) để kế thừa PHP
  của domain chính, và đặt domain chính sang version cần thiết (`php_set_vhost_versions`).
  Production thật: dùng DNS + subdomain docroot→public + set PHP cho chính vhost subdomain.

cpanel db:list


**域名未指向DNS时访问网站**：使用服务器的mod_userdir URL：`https://<server-host>/~<cpaneluser>/`（对应`public_html`）或`https://<server-host>/~<cpaneluser>/<subdir>/`对应子文件夹。这是域名未指向时验证静态文件+PHP的方法。注意：
- `public_html/*`下的静态文件和PHP可通过用户目录访问。
- **Node.js/Passenger和子域虚拟主机无法通过用户目录运行**——需要真实DNS指向才能命中正确虚拟主机。未设置DNS时，只能验证到API返回`enabled=1`的程度。
- 直接访问`https://<domain>/`会进入默认虚拟主机，直到DNS设置正确。
- **通过用户目录访问时的PHP版本（CloudLinux）**：作为**子域文档根目录**的文件夹在通过用户目录访问时会应用**账户默认PHP版本**（通常为7.4），而非为子域设置的版本。若要在未设置DNS时验证需要新版本PHP的应用（如Laravel/8.3）：将应用部署到`public_html`下的**普通子文件夹**（从未作为子域文档根目录）以继承主域名的PHP版本，并将主域名设置为所需版本（`php_set_vhost_versions`）。生产环境：使用DNS + 子域文档根目录指向public + 为子域虚拟主机设置PHP版本。

Bài học thực chiến (đã kiểm chứng trên server thật)

实战经验（已在真实服务器上验证）

fileop
path semantics:
```
destfiles
```
tính tương đối thư mục chứa nguồn, KHÔNG phải home. Khi extract, dùng
```
destfiles="."
```
(giải nén tại thư mục chứa archive). Khi move, dùng đường dẫn tuyệt đối (lấy từ trường
```
fullpath
```
của
```
list_files
```
).
index.html
che
index.php
: Apache/LiteSpeed ưu tiên
```
index.html
```
.
```
deploy:wp
```
tự đổi tên nó thành
```
index.html.default-bak
```
; nếu deploy thủ công, nhớ làm bước này.
Tiền tố MySQL:
```
deploy:wp
```
tự ghép tiền tố cho DB/user (xem
```
cpanel-database
```
).
Git clone (
VersionControl::create
):
```
repository_root
```
phải tuyệt đối;
```
source_repository
```
là JSON object
```
{"url":"..."}
```
(không phải string); cần
```
name
```
; thư mục đích phải chưa tồn tại.
```
git:clone
```
lo hết các điểm này.
Node.js (
PassengerApps
): hàm đúng là
```
register_application
```
, tham số
```
domain
```
(số ít). Không
```
npm install
```
được qua API → app zero-dep hoặc bundle
```
node_modules
```
.

fileop
路径语义：
```
destfiles
```
是相对于源文件所在目录的路径，而非主目录。解压时使用
```
destfiles="."
```
（在归档文件所在目录解压）。移动时使用绝对路径（从
```
list_files
```
的
```
fullpath
```
字段获取）。
index.html
覆盖
index.php
：Apache/LiteSpeed优先加载
```
index.html
```
。
```
deploy:wp
```
会自动将其重命名为
```
index.html.default-bak
```
；若手动部署，需记得执行此步骤。
MySQL前缀：
```
deploy:wp
```
会自动为数据库/用户添加前缀（查看
```
cpanel-database
```
）。
Git克隆（
VersionControl::create
）：
```
repository_root
```
必须为绝对路径；
```
source_repository
```
是JSON对象
```
{"url":"..."}
```
（而非字符串）；需要指定
```
name
```
；目标文件夹必须不存在。
```
git:clone
```
命令会处理所有这些细节。
Node.js（
PassengerApps
）：正确的函数是
```
register_application
```
，参数为
```
domain
```
（单数）。无法通过API执行
```
npm install
```
→ 使用零依赖应用或打包
```
node_modules
```
。

An toàn & lưu ý

安全与注意事项

Deploy vào
```
public_html
```
sẽ ghi đè trang mặc định. Nếu docroot đã có site, xác nhận với người dùng trước; cân nhắc deploy vào thư mục con + subdomain.
Mật khẩu DB đặt trong nháy đơn để shell không diễn giải ký tự đặc biệt; mật khẩu yếu có thể bị cPanel từ chối.
```
deploy:wp
```
không tạo admin WordPress — bước đó do người dùng làm qua trình duyệt (an toàn hơn việc hard-code mật khẩu admin).
Liên kết:
```
cpanel-database
```
(DB),
```
cpanel-domain
```
(subdomain cho site mới),
```
cpanel-debug
```
(đọc error_log nếu deploy lỗi).

部署到
```
public_html
```
会覆盖默认页面。如果文档根目录已有站点，需先与用户确认；考虑部署到子文件夹+子域名。
数据库密码使用单引号包裹，避免shell解析特殊字符；弱密码可能被cPanel拒绝。
```
deploy:wp
```
不会创建WordPress管理员账户——该步骤由用户通过浏览器完成（比硬编码管理员密码更安全）。
相关链接：
```
cpanel-database
```
（数据库操作）、
```
cpanel-domain
```
（为新站点创建子域名）、
```
cpanel-debug
```
（部署出错时读取error_log）。",

cpanel-deploy

Original

Translation

cPanel — Deploy mã nguồn

cPanel — 部署源代码

Các lệnh thao tác file

文件操作命令

Deploy WordPress trọn gói (một lệnh)

一键部署完整WordPress

Ví dụ: deploy vào document root chính

示例：部署到主文档根目录

Deploy static site (HTML/CSS/JS hoặc source build sẵn)

部署静态站点（HTML/CSS/JS或已构建的源代码）

nén & deploy cả thư mục

压缩并部署整个文件夹

hoặc deploy 1 file zip có sẵn

或者部署已有的zip文件

Deploy PHP app + MySQL (đã kiểm chứng)

部署PHP应用+MySQL（已验证）

1. (tùy chọn) tạo subdomain cho app

1.（可选）为应用创建子域名

2. tạo database

2. 创建数据库

3. deploy mã nguồn (KHÔNG kèm file secret)

3. 部署源代码（不包含机密文件）

4. ghi file config chứa credential TRỰC TIẾP trên server (không nằm trong zip)

4. 在服务器上直接写入包含凭证的配置文件（不在zip包中）

Deploy Laravel KHÔNG cần SSH (đã kiểm chứng end-to-end)

无需SSH部署Laravel（已端到端验证）

=== LÀM LOCAL ===

=== 本地操作 ===

1. Tạo app + build vendor khớp PHP server (vd server PHP 8.3 → platform 8.3)

1. 创建应用并构建与服务器PHP版本匹配的vendor目录（例如服务器PHP 8.3 → 指定platform 8.3）

2. DÙNG SQLITE: pre-migrate LOCAL (khỏi chạy artisan migrate trên server)

2. 使用SQLITE：本地预迁移（无需在服务器上运行artisan migrate）

=== DEPLOY (1 lệnh) ===

=== 部署（一键命令） ===

Trỏ document root vào public/ + đặt PHP version cho vhost

将文档根目录指向public/并为虚拟主机设置PHP版本

Clone Git repo về hosting (đã kiểm chứng)

克隆Git仓库到主机（已验证）

path tương đối tự resolve thành tuyệt đối; tên repo tự suy từ basename

相对路径会自动解析为绝对路径；仓库名称自动从basename推断

Deploy Node.js app (Passenger — đã kiểm chứng đăng ký)

部署Node.js应用（Passenger — 已验证注册）

1. subdomain làm Application URL

1. 创建子域名作为应用URL

2. đưa code vào app root (KHÁC docroot web; vd thư mục 'nodeapp')

2. 将代码放入应用根目录（与Web文档根目录不同；例如nodeapp文件夹）

3. đăng ký app (app_root, domain, app_name)

3. 注册应用（app_root, domain, app_name）

Deploy thủ công một ứng dụng bất kỳ (file ops thô)

手动部署任意应用（原始文件操作）

Kiểm chứng sau deploy

部署后验证

1. File đã vào đúng chỗ

1. 确认文件已上传到正确位置

2. wp-config.php đúng credential

2. 确认wp-config.php的凭证正确

3. Database tồn tại

3. 确认数据库存在

Bài học thực chiến (đã kiểm chứng trên server thật)

实战经验（已在真实服务器上验证）

An toàn & lưu ý

安全与注意事项

2. 将代码放入应用根目录（与Web文档根目录不同；例如
`nodeapp`
文件夹）