@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/providers/aliyun/cli/hosting.md

@@ -0,0 +1,226 @@
+# Aliyun CLI: Hosting (OSS + CDN)
+
+## When to Use Hosting Commands
+
+| Goal | Command | Notes |
+|------|---------|-------|
+| Deploy static site | `ossutil cp -r` + `cdn refresh` | Main deployment |
+| List CDN domains | `aliyun cdn DescribeDomains` | Check domains |
+| Add CDN domain | `aliyun cdn AddCdnDomain` | Configure CDN |
+| Refresh CDN cache | `aliyun cdn RefreshObjectCaches` | Clear cache |
+| SSL certificate | `aliyun cdn SetCdnDomainSSLCertificate` | HTTPS config |
+| Set index page | `ossutil website` | Configure hosting |
+
+## Decision Tree for Hosting Operations
+
+```
+Need to deploy static content?
+├── Deploy to shared env → deploy_stack --preview --provider aliyun
+├── Deploy to OSS → ossutil cp -r ./dist oss://bucket/
+├── Refresh CDN cache → aliyun cdn RefreshObjectCaches
+├── Add custom domain → aliyun cdn AddCdnDomain
+└── Configure SSL → aliyun cdn SetCdnDomainSSLCertificate
+```
+
+## Deploy Static Site
+
+### Basic Deployment to OSS
+
+```bash
+# Upload all files
+ossutil cp -r ./dist oss://my-bucket/ --force
+
+# Set index page
+ossutil website oss://my-bucket/ --index index.html --error 404.html
+```
+
+### With CDN Refresh
+
+```bash
+# Upload files
+ossutil cp -r ./dist oss://my-bucket/ --force
+
+# Refresh CDN cache (entire bucket)
+aliyun cdn RefreshObjectCaches \
+  --ObjectType directory \
+  --ObjectPath http://my-bucket.oss-cn-shanghai.aliyuncs.com/
+```
+
+### With Build Environment Variables
+
+```bash
+# Set env vars before build
+export BACKEND_URL=https://api.example.com
+pnpm --filter web build
+
+# Upload
+ossutil cp -r ./dist oss://my-bucket/ --force
+```
+
+## CDN Management
+
+### List CDN Domains
+
+```bash
+aliyun cdn DescribeDomains --region cn-shanghai
+```
+
+### Add CDN Domain
+
+```bash
+aliyun cdn AddCdnDomain \
+  --DomainName example.com \
+  --CdnType web \
+  --SourceType oss \
+  --SourceDomain my-bucket.oss-cn-shanghai.aliyuncs.com \
+  --Region cn-shanghai
+```
+
+### Enable HTTPS
+
+```bash
+# Add SSL certificate
+aliyun cdn SetCdnDomainSSLCertificate \
+  --DomainName example.com \
+  --CertType upload \
+  --SSLProtocol true \
+  --CertFile /path/to/cert.pem \
+  --KeyFile /path/to/key.pem
+```
+
+### Set Cache Rules
+
+```bash
+# Set cache for specific file types
+aliyun cdn SetFileCacheConfig \
+  --CacheType 30 \
+  --CacheUrlPropertyList "*.js,*.css,*.png,*.jpg,*.html"
+```
+
+### Set Referer Whitelist
+
+```bash
+aliyun cdn SetDomainRefererList \
+  --DomainName example.com \
+  --ReferList "example.com,www.example.com" \
+  --ReferType 1  # 1 = whitelist
+```
+
+## Refresh CDN Cache
+
+### Refresh Single File
+
+```bash
+aliyun cdn RefreshObjectCaches \
+  --ObjectType File \
+  --ObjectPath http://example.com/index.html
+```
+
+### Refresh Directory
+
+```bash
+aliyun cdn RefreshObjectCaches \
+  --ObjectType Directory \
+  --ObjectPath http://example.com/static/
+```
+
+### Refresh by Tag
+
+```bash
+# Refresh all files with specific tag (requires file management)
+aliyun cdn RefreshObjectCachesByTag \
+  --Tag "deploy:20240115"
+```
+
+### Query Refresh Status
+
+```bash
+aliyun cdn DescribeRefreshTasks \
+  --TaskId "task-xxxxx"
+```
+
+## URL Patterns
+
+| Environment | URL Pattern |
+|-------------|-------------|
+| OSS Origin | `https://{bucket}.{region}.aliyuncs.com` |
+| CDN Domain | `https://{cdn-domain}` |
+| Custom Domain | `https://{custom-domain}` |
+
+## Agent Workflows
+
+### Workflow: Deploy Web App with CDN
+
+```bash
+# 1. Upload to OSS
+ossutil cp -r ./dist oss://my-bucket/ --force
+
+# 2. Refresh CDN
+aliyun cdn RefreshObjectCaches \
+  --ObjectType directory \
+  --ObjectPath http://my-bucket.oss-cn-shanghai.aliyuncs.com/
+
+# 3. Verify
+curl -I https://my-bucket.oss-cn-shanghai.aliyuncs.com/index.html
+```
+
+### Workflow: Deploy with Custom Domain
+
+```bash
+# 1. Add CDN domain
+aliyun cdn AddCdnDomain \
+  --DomainName example.com \
+  --CdnType web \
+  --SourceType oss \
+  --SourceDomain my-bucket.oss-cn-shanghai.aliyuncs.com
+
+# 2. Configure DNS (manual)
+# Add CNAME: example.com -> example.com.w.kunlungr.com
+
+# 3. Wait for DNS propagation (5-10 min)
+
+# 4. Add SSL certificate
+aliyun cdn SetCdnDomainSSLCertificate \
+  --DomainName example.com \
+  --CertType upload \
+  --SSLProtocol true \
+  --CertFile /path/to/cert.pem \
+  --KeyFile /path/to/key.pem
+
+# 5. Upload and refresh
+ossutil cp -r ./dist oss://my-bucket/ --force
+aliyun cdn RefreshObjectCaches --ObjectType directory \
+  --ObjectPath http://example.com/
+```
+
+### Workflow: Debug Deployment
+
+```bash
+# 1. Check OSS bucket
+ossutil ls oss://my-bucket/ --max-size 10
+
+# 2. Check index.html exists
+ossutil stat oss://my-bucket/index.html
+
+# 3. Check CDN domain
+aliyun cdn DescribeCdnDomainDetail --DomainName example.com
+
+# 4. Test origin directly
+curl -I https://my-bucket.oss-cn-shanghai.aliyuncs.com/index.html
+
+# 5. Test CDN
+curl -I https://example.com/index.html
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `No index.html found` | Directory doesn't contain index.html | Ensure correct `--dir` path |
+| `404 on routes` | SPA routing not working | Set index page in OSS website config |
+| `Stale content` | CDN cache not cleared | Refresh CDN after deploy |
+| `CDN not working` | DNS not propagated | Wait for CNAME propagation |
+| `SSL not ready` | Certificate provisioning | Wait 1-10 minutes |
+| `CORS errors` | CDN not allowing origin | Configure CDN referer whitelist |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/aliyun/cli/setup.md

@@ -0,0 +1,235 @@
+# Aliyun CLI Setup & Authentication
+
+## When to Use CLI vs SDK vs REST API
+
+**Use CLI when:**
+- Deploying functions from CI/CD
+- Running one-off administrative tasks
+- Scripting cloud operations
+- Initial setup and configuration
+
+**Use SDK when:**
+- Building applications that interact with Aliyun
+- Need programmatic access from within functions
+- Complex business logic involving Aliyun services
+
+**Use REST API when:**
+- CLI/SDK doesn't support specific operation
+- Building custom integrations
+
+## Installation
+
+### Prerequisites
+
+- Node.js 14.x or later
+- Python 3.x (for fun CLI)
+
+### Install fun CLI (Function Compute)
+
+```bash
+npm install @alicloud/fun -g
+```
+
+Verify installation:
+
+```bash
+fun --version
+```
+
+### Install ossutil (OSS)
+
+```bash
+# Download ossutil
+curl -o ossutil https://gosspublic.alicdn.com/ossutil/1.7.9/ossutil64
+chmod +x ossutil
+sudo mv ossutil /usr/local/bin/
+
+# Configure
+ossutil config
+# Follow prompts to enter AccessKey and region
+```
+
+### Install aliyun CLI (General)
+
+```bash
+pip install aliyun-cli
+# or
+npm install @alicloud/alicloud-cli -g
+```
+
+### Install serverless devs
+
+```bash
+npm install @serverless-devs/s -g
+```
+
+## Authentication Methods
+
+### Method 1: Access Key (Recommended for CLI)
+
+```bash
+# Configure aliyun CLI
+aliyun configure
+
+# Or set environment variables
+export ALICLOUD_ACCESS_KEY=your-access-key-id
+export ALICLOUD_SECRET_KEY=your-access-key-secret
+export ALICLOUD_REGION=cn-shanghai
+```
+
+### Method 2: RAM Role (Recommended for CI/CD)
+
+Create RAM role with appropriate permissions, then assume role:
+
+```bash
+aliyun ram AssumeRole \
+  --RoleArn acs:ram::xxx:role/AliyunFunctionComputeRole \
+  --RoleSessionName ci-session
+```
+
+### Method 3: STS Token (For temporary access)
+
+```javascript
+const OSS = require('ali-oss');
+const STS = require('aliyun-sdk').STS;
+
+const sts = new STS({
+  accessKeyId: process.env.ALICLOUD_ACCESS_KEY,
+  accessKeySecret: process.env.ALICLOUD_SECRET_KEY
+});
+
+const result = await sts.assumeRole({
+  RoleArn: 'acs:ram::xxx:role/upload-role',
+  RoleSessionName: 'upload-session'
+});
+```
+
+## Credential Selection Decision Tree
+
+```
+Need to run Aliyun commands?
+├── Local development
+│   └── aliyun configure (interactive)
+├── CI/CD pipeline
+│   ├── Use environment variables (ALICLOUD_ACCESS_KEY/KEY)
+│   └── Use RAM role for better security
+├── From within FC function
+│   └── Use service credentials (automatic injection)
+└── Never commit credentials to git
+```
+
+## Verifying Authentication
+
+### Check Login Status
+
+```bash
+# aliyun CLI
+aliyun ecs DescribeInstances --region cn-shanghai
+
+# fun CLI
+fun --access-key-id $ALICLOUD_ACCESS_KEY --access-key-secret $ALICLOUD_SECRET_KEY
+```
+
+### Check OSS
+
+```bash
+ossutil ls oss://
+```
+
+## Environment Variables Reference
+
+| Variable | Description | Source |
+|----------|-------------|--------|
+| `ALICLOUD_ACCESS_KEY` | Aliyun access key ID | Manual or `aliyun configure` |
+| `ALICLOUD_SECRET_KEY` | Aliyun access key secret | Manual or `aliyun configure` |
+| `ALICLOUD_REGION` | Default region | Manual or `aliyun configure` |
+| `FUNC_ACCESS_KEY_ID` | FC-specific credential | For FC function calls |
+| `FUNC_ACCESS_KEY_SECRET` | FC-specific credential | For FC function calls |
+
+## Project-Level Configuration
+
+### fun CLI (template.yml)
+
+No separate config file needed - credentials passed via env vars or CLI flags.
+
+### ossutil
+
+```bash
+# Configure with custom endpoint
+ossutil config
+# Enter:
+# - Access Key ID
+# - Access Key Secret
+# - Default region (cn-shanghai)
+# - Output format (json)
+```
+
+### serverless devs (s.yaml)
+
+```yaml
+edition: 1.0.0
+services:
+  my-app:
+    component: fc
+    props:
+      region: ${ALICLOUD_REGION}
+      access: default  # uses default credentials
+```
+
+## CLI Configuration
+
+### Set Default Region
+
+```bash
+export ALICLOUD_REGION=cn-shanghai
+```
+
+### Set Output Format
+
+```bash
+aliyun configure set --output json
+```
+
+### View Current Config
+
+```bash
+cat ~/.aliyun/config.json
+```
+
+## Security Best Practices
+
+1. **Never commit credentials** - Add to `.gitignore`
+2. **Use environment variables in CI/CD** - Don't hardcode secrets
+3. **Use RAM roles** - Instead of root credentials
+4. **Use least privilege** - Create dedicated RAM policies
+5. **Rotate credentials regularly** - Access keys can be rotated
+
+### .gitignore Example
+
+```
+# Aliyun credentials
+.env
+.env.*
+aliyun-cli-config.json
+ossutil-config.ini
+
+# Function compute
+.node-version
+.template.yml.bak
+
+# Build outputs
+dist/
+build/
+```
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| `command not found: fun` | CLI not installed | `npm install @alicloud/fun -g` |
+| `command not found: ossutil` | CLI not installed | Download and install ossutil |
+| `InvalidAccessKeyId` | Wrong credentials | Verify AccessKey in RAM console |
+| `SignatureDoesNotMatch` | Secret key mismatch | Check ALICLOUD_SECRET_KEY |
+| `Permission denied` | Insufficient RAM permissions | Check RAM policy |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`