aliyun-deploy

Use Cases

A static site (SPA or multi-page) provides Alibaba Cloud OSS storage + CDN acceleration for HTTPS access.

Resource Scope: The domain, DNS resolution, OSS, and CDN are all under the same Alibaba Cloud account. If the domain is hosted by a third party, you need to map the DNS steps yourself.

Dependencies

Capability	Path
Domain/DNS	aliyun-domain-skills/SKILL.md
OSS	aliyun-oss-skills/SKILL.md
CDN	aliyun-cdn-skills/SKILL.md

Environment: Node.js (build), Python 3 (invoke scripts), certbot (apply for certificates).

Before execution, ensure the requirements.txt。

Pre-checks

Credentials: Check the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID/SECRET, or the project root directory .env。
Permissions: Requires OSS (read/write Bucket/objects) and CDN (domain management/certificate/refresh) permissions; stop immediately on a 403 error and continue only after the user completes the RAM policy.

Project Configuration (`.aliyun-config.json`）

Deployment information is written to the project root directory for idempotent re-runs. Two formats are supported:

Single-project configuration (object format)

{
  "version": 1,
  "domain_apex": "example.com",
  "cdn_domain": "www.example.com",
  "oss_bucket": "my-app-static",
  "oss_region": "oss-cn-hangzhou",
  "cdn_cname_target": "xxx.w.kunlunsl.com",
  "origin_mode": "private_with_cdn_auth",
  "last_deploy_at": "2026-03-24T12:00:00Z"
}

Multi-project configuration (array format)

Supports managing multiple deployment targets in the same repository (such as multiple environments or multiple applications):

[
  {
    "project": "my-app-prod",
    "version": 1,
    "domain_apex": "example.com",
    "cdn_domain": "www.example.com",
    "oss_bucket": "my-app-prod",
    "oss_region": "oss-cn-hangzhou",
    "cdn_cname_target": "xxx.w.kunlunsl.com",
    "origin_mode": "private_with_cdn_auth",
    "last_deploy_at": "2026-03-24T12:00:00Z"
  },
  {
    "project": "my-app-staging",
    "version": 1,
    "domain_apex": "example.com",
    "cdn_domain": "staging.example.com",
    "oss_bucket": "my-app-staging",
    "oss_region": "oss-cn-hangzhou",
    "cdn_cname_target": "yyy.w.kunlunsl.com",
    "origin_mode": "private_with_cdn_auth",
    "last_deploy_at": "2026-03-24T10:00:00Z"
  }
]

Field Descriptions：

Field	Type	Required	Description
`project`	string	Required for multi-project	Project identifier, used to distinguish different configurations
`version`	int	Yes	Configuration format version, currently 1
`domain_apex`	string	Yes	Root domain, used for DNS resolution
`cdn_domain`	string	Yes	CDN accelerated domain (full hostname)
`oss_bucket`	string	Yes	OSS Bucket name
`oss_region`	string	Yes	OSS region, such as `oss-cn-hangzhou`
`cdn_cname_target`	string	Yes	CNAME target address assigned by CDN
`origin_mode`	string	No	Origin mode:`private_with_cdn_auth`(private origin fetch by default) or `public`
`last_deploy_at`	string	No	Last deployment time in ISO 8601 format

Incremental Update

Object format: If the configuration exists and the fields are complete (Bucket, region, CDN domain, etc.), this time only execute:build → upload to OSS → refresh CDN
Array format: Prompt the user to select the project to deploy (distinguished by the project field); after selection, only update that project's configuration

If the user requests changing the domain/Bucket/CDN/certificate, or adding a project configuration, then go through the full workflow.

Items Requiring User Confirmation (the Agent must not decide on behalf of the user)

Category	Confirmation Content
Domain	Deployment domain, FQDN covered by the certificate
OSS	Bucket name, region, upload path prefix
CDN	Accelerated domain (full hostname)
Security	Private Bucket + CDN origin pull (default) or public read

Process: Query existing resources in the account → Display list → User selects → Execute.

Main process

1. Domain

Use domain-skill to query the account's domain list
After the user selects, subsequent CNAME/TXT records will be added to that domain's cloud DNS

2. OSS Bucket

Use oss-skill to query/create a Bucket
Default private ACL, paired with CDN private origin pull
Enable static website: default homepage index.html, 404 page same as homepage (SPA)

3. Build and Upload

Run build (npm run build etc.)
Upload artifacts to the specified path in the Bucket, ensuring index.html is at the root path
Refresh CDN after deployment cache

4. CDN Accelerated Domain

Use cdn-skill to add/configure an accelerated domain
Business type：web(images and small files)
Origin: OSS domain, enable private origin pull
Root path: Ensure accessing / returns index.html
Check ICP filing before adding (domestic acceleration)

5. DNS Configuration

5A — CNAME Access

Obtain the CNAME target assigned by CDN
Add a CNAME record in cloud DNS pointing to that target

5B — Certificate Verification (DNS-01)

certbot application:certbot certonly --manual --preferred-challenges dns -d <域名>
Add the _acme-challenge TXT record as prompted
After verification passes, obtain fullchain.pem and privkey.pem

6. HTTPS Configuration

Use cdn-skill to upload the certificate and enable HTTPS
It is recommended to enable Force HTTPS and HTTP/2
Certificate validity period is 90 days, and it must be reapplied for before expiration

7. Enable and Acceptance

Enable the accelerated domain (if it is in a disabled state)
Access https://<加速域名>/ to verify that the root path returns index.html
Check that there are no warnings for CNAME or the certificate chain

8. Wrap-up

Update .aliyun-config.json(for object format, update directly; for array format, update the corresponding project entry, or append a new configuration)
Return the HTTPS access address, and remind about certificate renewal and the subsequent release process (upload + refresh)

Troubleshooting

Symptom	Cause	Handling
403	Insufficient RAM permissions	Stop immediately and complete the policy
403	Private Bucket origin pull configuration error	Check OSS permissions and CDN origin configuration
Access `/` 404	Root path not mapped to `index.html`	Check the OSS default homepage configuration and file location
Blank page	SPA route 404	Set the OSS error page to `index.html`
Old resources	CDN cache not refreshed	Perform cache refresh
Certificate error	Certificate does not match the domain	Check SAN and certificate chain integrity
CNAME not taking effect	DNS propagation delay	`dig`/`nslookup` verify with

Billing notice

Possible costs: OSS storage/requests, CDN traffic/HTTPS, domain renewal. Let's Encrypt certificates are free.