deploy-to-hosting

部署到托管服务

将已有项目（位于本地磁盘或 Git 仓库中）部署到 Hostinger 网站。根据提示词构建新网站（设计、商店、博客）属于 hostinger-headless 技能；本技能会直接使用现有代码。

调用操作

• 在首次调用每项操作之前，先阅读 search 返回的 inputSchema。如果下方某个名称被拒绝并提示未知，请搜索该步骤要执行的操作（例如“部署静态网站”）。
• 使用 multi-execute 批量读取；值可通过 $steps.<i>.<path> 在步骤间传递。批次只能串联来自同一服务的操作——Hostinger Connector 会将 hosting、wordpress 和 agency-hosting 作为独立服务运行。
• 每次部署都会覆盖网站当前内容。首次向已有内容的网站部署前，先与用户确认目标域名。

1. 选择目标网站

• 如果项目中有 .hostinger/site.json：复用其中的 domain 和 username（或 website_uid）。
• 否则，使用 hosting_websites_list（Shared 和 Cloud；按子字符串匹配并选择完全匹配的条目）和 agency-hosting_websites_list-plan（Agency；保留 details.uid）查找域名。
• 如果尚无网站：
  • Shared 和 Cloud：选择一个域名（用户自己的域名，或 hosting_domains_generate-free-subdomain 生成的域名）以及来自 hosting_orders_list 的 order_id，然后调用 hosting_websites_create。只有新套餐中的首个网站需要 datacenter_code（取自 hosting_datacenters_list 的第一项）。每隔 10–15 秒使用 domain 轮询 hosting_websites_list-setups，直到 status: completed——在此之前，上传和部署会返回 404 或 409。
  • Agency：使用 flavor: "php-fpm" 调用 agency-hosting_website-setups_create（对于已构建的前端，再加上 type: "node-static"），settings.php.version 取自 agency-hosting_php_list-versions-for-order，datacenter_code 取自 agency-hosting_datacenters_list。轮询 agency-hosting_website-setups_status，直到状态为 completed；该操作会返回 website_uid。
• Node.js 应用可运行于 Business 和 Cloud 套餐（hosting_orders_list 中的 hostinger_business_*、cloud_*）。其他套餐请在本地构建，并将构建输出作为静态网站部署。

2. 选择部署方式

Shared 和 Cloud，在本地的 hostinger-api-mcp 服务上： 一次操作即可完成所有部署 — 使用 hosting_deploy，并提供 domain 以及 path（此计算机上的目录）或 git: { repository: "owner/name", branch }。提供目录时，它会检测项目类型并自行打包（跳过 node_modules、.git 和 .env 文件，并将 .env 文件列入 skippedFiles，以便你使用 hosting_nodejs_replace-environment-variables 设置其值；它不会读取 .gitignore，因此请勿将构建输出放在该目录中），然后完成上传、构建和 Git 设置。不要打包该目录，也不要手动调用上传和构建操作。

项目	hosting_deploy 将其视为
纯 HTML/CSS/JS，或框架的静态构建输出	static — 原样解压
含有构建脚本、启动脚本或服务器依赖项（Next.js、Nuxt、Express、Vite……）的 package.json	nodejs — 启动构建并返回 buildUuid
PHP 代码，无构建步骤	static
WordPress 插件目录（包含 Plugin Name: 标头）或主题目录（style.css 中包含 Theme Name:）	wordpress-plugin / wordpress-theme；activate: true 会激活主题
来自其他位置的完整 WordPress 站点	wordpress-site，并提供 databaseDump — 参见 migrate-to-hosting 技能

• 传入 type 可覆盖自动检测结果。对于归档文件（无法检查归档内容），以及目录符合多种 WordPress 类型的情况（hosting_deploy 会因类型不明确而拒绝），此参数为必填项。
• Node.js 构建设置取自项目；检测会识别框架和构建脚本。如果检测有误，请设置 appType、outputDirectory、buildScript、entryFile、nodeVersion（默认值为 22）、rootDirectory 或 packageManager。TypeScript 或其他已编译的服务器应用始终需要将 entryFile 设为构建后的文件（例如 dist/server.js）：检测只会猜测根目录中的文件，因此构建会报错 "Entry file not found"。对于 express、fastify、hono、react-router 和 other，入口文件相对于根目录；对于 nest、nuxt、nitro、astro 和 svelte-kit，则相对于输出目录（main.js，而不是 dist/main.js）；Next.js 会忽略此设置。各框架的具体值请参阅 Hostinger 文档中的 Node.js（Supported Frameworks、Build Settings）。
• 静态、PHP、插件和主题部署会在调用返回时立即生效。WordPress 站点导入仅会启动（status: import_started），几分钟后才完成解压；在此之前不要报告导入已完成，也不要进行验证。Node.js 构建在服务端运行：请参见第 3 步。

Agency： 由网站类型决定（agency-hosting_websites_get）：创建为 node-static 的站点使用 agency-hosting_deploy-node-static-website，如果项目包含构建步骤，此操作会运行构建；其他所有站点均使用 agency-hosting_deploy-php-application，该操作会原样解压归档文件。它们会同步部署归档文件：调用返回时站点即已上线。Agency 站点上的 WordPress 插件和主题需从 wp-admin 安装。

Agency 归档文件的规则（归档文件命名为 name_YYYYMMDD_HHMMSS.zip）以及自行构建的归档文件规则：

• 静态： 先在本地构建。index.html 必须位于归档根目录中，不能放在文件夹内：cd dist && zip -r ../site_20260101_120000.zip .
• Node.js 源码： 不包含 node_modules/、构建输出（dist/、.next/、build/）、.env* 或任何与 .gitignore 匹配的文件；大小最多为 50 MB。git archive --format=zip -o app_20260101_120000.zip HEAD 会准确生成已提交的文件 — 请说明未提交的更改不会包含在内。

hosting_deploy 和 agency-hosting_deploy-* 操作会从此计算机读取文件，因此只有本地服务能访问这些文件。在托管服务端（mcp.hostinger.com）上，search 无法找到这些文件 — 请按下文所述自行上传文件。

不使用本地部署操作（托管服务；仅 Agency 使用本地服务）

1. 获取上传凭据：hosting_files_generate-upload-url（username、domain）；Agency：agency-hosting_files_generate-upload-url（website_uid）。两者都会返回 url、auth_key 和 rest_auth_key，这些凭据用于验证上传，而不是 API 令牌。
2. 使用 TUS 上传每个文件，其中 DEST 是文件在网站存储中的路径：

SIZE=$(wc -c < "$FILE" | tr -d ' ')
curl -sS -X POST "$URL/$DEST?override=true" -H "X-Auth: $AUTH_KEY" -H "X-Auth-Rest: $REST_AUTH_KEY" -H "Tus-Resumable: 1.0.0" -H "Upload-Length: $SIZE" -H "Upload-Offset: 0"
curl -sS -X PATCH "$URL/$DEST?override=true" -H "X-Auth: $AUTH_KEY" -H "X-Auth-Rest: $REST_AUTH_KEY" -H "Tus-Resumable: 1.0.0" -H "Content-Type: application/offset+octet-stream" -H "Upload-Offset: 0" --data-binary "@$FILE"

第一次调用返回 201，第二次返回 204，并带有一个 Upload-Offset 标头，其值等于文件大小。override=true 可确保重试安全。 3. 使用已上传的文件进行部署（RANDOM8 是任意新生成的 8 字符字符串，例如 $(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 8)）：

项目	DEST	然后
静态站点或 PHP	site.zip	使用 archive_path: "site.zip" 调用 hosting_websites_deploy-static-site-archive
Node.js	app.zip	使用 archive_path: "app.zip" 调用 hosting_nodejs_build-settings-from-archive，然后使用这些设置、source_type: "archive" 和 source_options.archive_path: "app.zip" 调用 hosting_nodejs_start-build
WordPress 插件	每个文件，路径为 wp-content/plugins/SLUG-RANDOM8/<path in the plugin>	使用 slug 和 plugin_path: "SLUG-RANDOM8" 调用 wordpress_plugins_deploy
WordPress 主题	每个文件，路径为 wp-content/themes/SLUG-RANDOM8/<path in the theme>	使用 slug、theme_path: "SLUG-RANDOM8" 和可选的 is_activated 调用 wordpress_themes_deploy
Agency，按原样解压	.h5g/site.zip	使用 archive_name: "site.zip" 调用 agency-hosting_files_import-website-from-archive
Agency node-static	.h5g/RANDOM8/app.zip	使用 archive_path: ".h5g/RANDOM8" 调用 agency-hosting_websites_build-nodejs-assets——指定目录，而不是文件

3. Node.js 构建

hosting_deploy 会立即返回一个 buildUuid；构建在服务端运行，需要几分钟。使用 hosting_get-deployment 跟踪构建（domain，可选的 buildUuid；默认使用最新构建），每隔 10–20 s 轮询一次，直到 build.state 为 completed 或 failed。该调用会返回构建、其日志和已存储的构建设置；传入之前的 logs.lines 作为 fromLine，即可只读取新输出。

• 构建失败：响应中已包含 analysis（每个构建仅获取一次；API 每分钟允许调用 5 次）。
• 检测错误（框架、output_directory，或构建输出中的入口文件，例如已编译应用的 dist/server.js）：重新部署，并设置 appType、outputDirectory、buildScript 或 entryFile。归档部署会在请求中发送这些设置，但不会更改已存储的设置；Git 部署也会存储这些值，因此后续推送会使用这些设置进行构建。

在不支持 hosting_deploy 或 hosting_get-deployment 的托管服务上：

• 完成以下上传步骤后，启动构建，并使用 hosting_nodejs_list-builds 和 hosting_nodejs_build（按 uuid）跟踪构建，每隔 10–20 s 轮询一次。
• 构建失败：每个构建调用一次 hosting_nodejs_analyse-failed-build（每分钟 5 次），如果分析结果为空，则调用 hosting_nodejs_build-logs。
• 检测错误：使用明确的值调用 hosting_nodejs_start-build，设置 source_type: "archive"，并将 source_options.archive_path 设为文档根目录中的归档文件名（使用 hosting_files_list-website-and-directories 检查文件是否存在）。使用 hosting_nodejs_update-build-settings 存储相同的值。
• 若要在构建前查看检测到的设置：使用 hosting_files_generate-upload-url 上传归档（其说明中包含 TUS 步骤），然后调用 hosting_nodejs_build-settings-from-archive。

4. 从 Git 自动部署

在本地服务器上，hosting_deploy 搭配 git: { repository: "owner/name", branch } 即可完成所有操作：它会找到能够访问仓库的 Git 安装，并按你指定的 type 部署。除非网站已经运行 Node.js 应用（或你传入了 appType 等 Node.js 设置），否则务必传入 type: "static" 或 "nodejs"：新网站不会被识别为 Node.js，而将 Node.js 仓库作为静态网站部署则会发布其源代码。然后：

• **PHP 和静态网站：**保存自动部署设置，并立即部署该分支；之后每次推送时也会部署；
• **Node.js 网站：**使用已保存的构建设置开始构建该分支；之后的推送也会以相同方式构建。Git 部署没有可供检测的内容，因此若尚未保存设置，请传入 appType 和 nodeVersion（取自 package.json 中的 engines），如果应用有构建步骤，还要传入 outputDirectory 和 buildScript；这些设置会为后续推送保存。

如果没有可用的安装，它会停止操作并说明情况：用户需要在 hPanel 的 Websites → Manage → Advanced → Git 中连接一次 GitHub 或 GitLab；此步骤没有 API。使用 hosting_get-deployment 确认，该工具会返回已保存的 gitAutoDeployment。

在托管服务器上手动操作：

1. hosting_git_list-installations。如果没有 active 安装（也要检查 status: "pending" 和 "suspended"），用户需要按上述方法在 hPanel 中连接一次 GitHub 或 GitLab。
2. 使用安装的 uuid 调用 hosting_git_list-installation-repositories，获取 owner、name 和 default_branch（每分钟最多调用 10 次）。
3. 使用 installation_uuid、owner、repository、branch 和可选的 directory 调用 hosting_git_update-auto-deployment-settings。
   • PHP 和静态网站会立即部署该分支，并在之后每次推送时再次部署。
   • 保存设置时，Node.js 网站不会克隆任何内容：使用相同的 source_options 和 source_type: "git" 调用 hosting_nodejs_start-build，开始首次构建。之后的推送会使用已保存的设置构建，因此请确保 hosting_nodejs_update-build-settings 中的设置正确。
4. 使用 hosting_git_auto-deployment-settings 确认。

Agency Plan 网站不支持 Git 操作；请部署归档文件。

5. 环境变量（Node.js）

hosting_nodejs_replace-environment-variables 会替换整组环境变量——未发送的变量都会被删除。

1. 调用 hosting_nodejs_list-environment-variables 获取当前键名。返回的值会显示为 ********；切勿将这些值发送回去。
2. 构建完整的变量集：包括所有当前键名和新增键名，并使用项目 .env 文件或用户提供的真实值。如果不知道某个现有键的真实值，请先询问——不要将其删掉。
3. 一次性发送整组变量；应用会重启。在构建时写入的值（Next.js 的 NEXT_PUBLIC_*、Vite 的 VITE_*）需要重新调用 hosting_nodejs_start-build。

键名只能包含大写字母、数字和下划线。切勿提交 .env 文件，也不要向用户复述机密值。

6. 数据库

• Node.js：hosting_databases_setup-website 会创建 MySQL 数据库，并将 DB_HOST、DB_PORT、DB_NAME、DB_USER、DB_PASSWORD 和 DATABASE_URL 写入环境变量，然后重启应用。如果其中任何键已存在，该操作会返回 422；请先使用第 5 节中的替换操作将其删除。
• **PHP：**使用 name、user、强度足够的随机 password 和 website_domain 调用 hosting_databases_create；然后从 hosting_databases_list 获取带前缀的完整名称。应用从服务器上不纳入 Git 的配置文件中读取凭据，并连接到 localhost 或 127.0.0.1。
• **Agency：**使用 agency-hosting_databases_create-website；应用连接到 localhost。
• hosting_databases_list 返回的 srvNNNN.hstgr.io 主机仅用于从 Hostinger 外部进行连接——切勿将其填入已部署的应用。

7. 验证并记录

curl -s -o /dev/null -w "%{http_code}\n" https://DOMAIN/
curl -s https://DOMAIN/ | grep -o "TEXT THE PROJECT RENDERS"

单凭 200 可能只是占位页面；请核对实际内容。新站点可能会短暂显示默认页面——先使用 hosting_cache_clear-website 清除缓存并重试，再判断部署是否失败。

在项目中写入 .hostinger/site.json，以便后续运行复用目标：{ "domain", "username" or "website_uid", "type": "static" | "nodejs" | "php" }，并保留其中已有的字段。