Despliegue y publicación

Este sitio es un sitio estático puro, y los artefactos de construcción pueden desplegarse en cualquier plataforma de alojamiento estático.

Construcción

npm run docs:build:all

El directorio de salida es docs/.vitepress/dist.

Nota: npm run docs:build solo construye el chino simplificado por defecto (preguntará si desea construir las versiones multilingües); use npm run docs:build:all para publicar el sitio multilingüe completo y npm run docs:dev para el desarrollo diario con vista previa en vivo.

Opción 1: GitHub Pages

1. En el repositorio, selecciona Settings → Pages y elige la rama y el directorio de despliegue;
2. O usa GitHub Actions para la construcción automática:

name: Deploy Docs

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build:all
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Opción 2: Vercel / Netlify

Con Vercel como ejemplo:

1. Importa el repositorio;
2. Comando de construcción: npm run docs:build:all;
3. Directorio de salida: docs/.vitepress/dist;
4. Haz clic en desplegar; admite despliegue automático y ramas de vista previa en cada push.

Opción 3: Nginx

# 将构建产物上传到服务器后
scp -r docs/.vitepress/dist user@server:/var/www/docs

Ejemplo de configuración de Nginx:

server {
  listen 80;
  server_name docs.example.com;

  root /var/www/docs;
  index index.html;

  # 前端路由回退
  location / {
    try_files $uri $uri/ /index.html;
  }
}

Dominio personalizado y HTTPS

• Vincula el dominio personalizado en la plataforma de alojamiento;
• Configura un registro CNAME que apunte a la plataforma;
• La plataforma emite y renueva automáticamente el certificado HTTPS.

Opción 4: Tencent Cloud COS + CDN

Una de las soluciones de bajo coste con mejor experiencia de acceso nacional: almacenamiento de objetos + aceleración CDN, adecuada para sitios orientados a usuarios de China continental.

1. Preparativos

• Cuenta de Tencent Cloud (los nuevos usuarios pueden obtener cuotas gratuitas, normalmente incluyen 10 GB de almacenamiento estándar y parte del tráfico, con validez de varios meses);
• Dominio con ICP filing (al usar un dominio acelerado por CDN de China continental, es obligatorio completar el registro ICP, con una revisión de aproximadamente 1-3 semanas, gratuito).

Explicación detallada del proceso de registro (registro ICP de Tencent Cloud)

Requisitos previos

1. El dominio debe haber completado la verificación de nombre real (en el registrador de dominios, normalmente efectiva en 1-3 días);
2. La cuenta de Tencent Cloud debe tener la verificación de nombre real completada y disponer de un recurso en la nube registrado como un servidor Tencent Cloud / servidor ligero (el registro debe estar vinculado a un recurso en la nube);
3. El contenido del sitio debe cumplir el «Reglamento de gestión del registro de servicios de información de Internet no comerciales»; el registro personal no puede implicar contenido comercial.

Paso	Operación	Materiales necesarios	Tiempo estimado
1. Verificación del dominio	Inicia sesión en la consola de registro de Tencent Cloud, introduce el dominio y el sistema identifica automáticamente el tipo de registro (primer registro/registro de acceso, etc.)	Dominio a registrar	Inmediato
2. Rellenar los datos	Rellena la información del sujeto (nombre personal/nombre de empresa, número de documento) y la información del servicio (nombre del sitio, dominio, responsable del sitio, contenido del servicio), sube las fotos del documento y el formulario de verificación	Anverso y reverso del DNI, foto sosteniéndolo (verificación facial por App), información del responsable del sitio, formulario de verificación (generado automáticamente)	Según preparación
3. Revisión inicial de Tencent Cloud	Tencent Cloud revisa la autenticidad e integridad de los datos	—	1-2 días laborables
4. Verificación por SMS	El MIIT envía un código de verificación; en 24 horas accede al sistema de registro del MIIT para completar la verificación	Código de verificación recibido por SMS	Dentro de 24 horas
5. Revisión de la autoridad reguladora	La oficina local de comunicaciones realiza la revisión final	—	Máximo 20 días laborables
6. Registro completado	Se recibe notificación por SMS/correo con el número de registro	—	Según notificación

Tras superar el registro hay que hacer dos cosas más:

1. Mostrar el número de registro en el pie de página del sitio, con enlace al sistema de registro del MIIT https://beian.miit.gov.cn, por ejemplo «粤ICP备2026000000号»;
2. Se recomienda solicitar además el registro de seguridad pública (dentro de los 30 días posteriores a la aprobación del registro), que es obligatorio en algunas provincias.

Consejos sobre el registro

• El primer registro personal suele completarse en 1-2 semanas; la eficiencia varía según la oficina reguladora de cada región;
• Durante el periodo de registro puedes publicar primero con el dominio predeterminado de COS o con nodos en el extranjero, y cambiar al dominio personalizado una vez aprobado;
• El registro es un servicio gratuito; ten cuidado con los servicios de gestoría de pago (la gestoría solo ofrece orientación para preparar los materiales).

2. Crear el bucket de almacenamiento

1. Entra en la consola de COS y crea un bucket de almacenamiento;
2. Elige una región cercana (por ejemplo, Guangzhou ap-guangzhou);
3. Selecciona lectura pública y escritura privada como permiso de acceso;
4. Activa la función «sitio web estático»: documento de índice index.html, documento de error 404.html.

3. Subir los artefactos de construcción

Tras construir, sube el directorio docs/.vitepress/dist:

npm run docs:build:all

# 方式一：控制台上传（对象 → 上传文件夹，选 dist 下所有文件）
# 方式二：使用 COSCLI 命令行工具
pip install coscmd
coscmd config -a <SecretId> -s <SecretKey> -b <bucket-name>-<appid> -r ap-guangzhou
coscmd upload -rs ./docs/.vitepress/dist/ /
coscmd list -r /

4. Conectar la aceleración CDN

1. Entra en la consola de CDN y añade el dominio acelerado;
2. La región de aceleración elige China continental (si no hay registro ICP, elige Hong Kong/ultramar, con velocidad media);
3. El tipo de origen elige COS, seleccionando el bucket recién creado;
4. Elige CNAME como método de conexión del dominio y añade el registro CNAME en el proveedor de DNS siguiendo las indicaciones;
5. Espera a que el CNAME tenga efecto (unos 10 minutos) y activa «Seguimiento de redirección 301/302 al origen» y «Origen por rangos (Range)».

5. Configurar HTTPS

5.1 Solicitar un certificado gratuito

1. Entra en la consola de SSL Certificates y elige «solicitar certificado gratuito»;
2. El tipo de certificado elige DV (validación de dominio) y vincula el dominio acelerado;
3. El método de verificación elige verificación DNS automática (se completa con un clic si el dominio está en Tencent Cloud o con resolución gestionada), y espera la emisión (de unos minutos a unas horas).

5.2 Activarlo en CDN

1. En CDN, en «Gestión de dominios → Configuración HTTPS», marca el certificado emitido;
2. Activa «Redirección forzada HTTP a HTTPS» (se recomienda activarla, con código de redirección 301);
3. Tras activarla, antes de la primera visita puedes hacer un precalentamiento (prefetch) de URL en «Refresco y precalentamiento» para mejorar la velocidad de la primera visita.

Notas sobre la facturación

• El certificado DV es gratuito y no tiene coste de renovación (el sistema avisa antes de la caducidad y puedes solicitarlo de nuevo);
• Ten en cuenta: el número de solicitudes HTTPS del CDN es un servicio de valor añadido, facturado a 0.04 CNY/10.000 solicitudes — como un sitio de documentación genera pocas solicitudes (cientos de miles al mes), el coste es de unos pocos yuanes, prácticamente despreciable; si no quieres generar ese coste, puedes desactivar la partida de facturación HTTPS en «Servicios de valor añadido» (no recomendado, perderías el cifrado).

5.3 Verificar el resultado del despliegue

curl -I https://docs.example.com
# 期望返回：HTTP/2 200
# 响应头包含：strict-transport-security 等安全头（可后续在 CDN 响应头配置中自定义）

5.4 Notas sobre la configuración CNAME

Al conectar al CDN, al dominio acelerado se le asigna un registro CNAME terminado en .cdn.dnsv1.com, que debe añadirse en el proveedor de resolución DNS:

Tipo de registro	Registro de host	Valor del registro	TTL
CNAME	docs	docs.example.com.cdn.dnsv1.com	600

• El tiempo de efecto suele ser de 10 minutos a 1 hora (depende del TTL);
• Un error de configuración (por ejemplo, configurarlo como registro A por error) hará que el dominio no se resuelva al CDN y la visita falle;
• Verificación: nslookup docs.example.com; si devuelve el destino CNAME, es correcto.

6. Configuración de caché

Para un sitio de documentación estática se recomienda establecer cachés largas para los recursos (la tasa de aciertos del CDN puede superar el 99%, casi sin tráfico de retorno al origen). Se configura en la consola de CDN en «Gestión de dominios → Configuración de caché».

6.1 Reglas de caché recomendadas

Prioridad	Tipo de coincidencia	Contenido	Tiempo de caché	Descripción
1	Sufijo de archivo	.html	10 minutos	Que los cambios de contenido se apliquen cuanto antes
2	Sufijo de archivo	.js .css	30 días	Los artefactos de VitePress llevan hash; se puede usar caché larga con confianza
3	Sufijo de archivo	.png .jpg .svg .webp .ico	30 días	Recursos de imágenes estáticas
4	Sufijo de archivo	.woff .woff2 .ttf	30 días	Archivos de fuentes
5	Todos los archivos	*	30 días	Regla de respaldo

6.2 Acierto de caché y tasa de aciertos

• Tras el acierto de caché, el CDN devuelve directamente el contenido del nodo periférico, sin generar tráfico de retorno al origen (ahorra la tarifa de retorno de 0.15 CNY/GB);
• La tasa de aciertos puede consultarse en la consola en «Análisis estadístico → Tasa de aciertos»; en un sitio de documentación suele mantenerse por encima del 99%;
• Si la tasa es baja, comprueba si está activada la opción «Ignorar la cadena de consulta»: al activarla, page.html?ref=a y page.html?ref=b aciertan la misma caché.

6.3 Refresco y precalentamiento de caché

• Refresco: se ejecuta tras actualizar contenido para limpiar la caché de los nodos periféricos (el refresco por URL es efectivo en tiempo real; el refresco por directorio tarda unos 5 minutos);
• Precalentamiento: guarda los recursos en los nodos periféricos de antemano, para lanzar nuevas versiones o grandes promociones, de modo que la primera visita no necesite volver al origen;
• Ruta en la consola: «Refresco y precalentamiento» → introduce URL/directorio → enviar;
• Forma automatizada: en el script de publicación, tras coscmd upload, llama a la API de refresco del CDN (API de refresco de URL / DescribeCdnHosts), o usa la notificación por eventos de COS para dispararlo.

6.4 Caché del navegador (caché secundaria)

Además de la caché de los nodos del CDN, el propio navegador también guarda recursos en caché. Puedes añadir lo siguiente en la «Configuración de cabeceras de respuesta HTTP» de COS o CDN para los recursos estáticos:

Cache-Control: public, max-age=2592000   # 30 天，用于带 hash 的静态资源
Cache-Control: no-cache                   # HTML 每次回源验证（配合 10 分钟节点缓存）

6.5 Caché por código de estado

Código de estado	Tiempo de caché recomendado	Descripción
200	Sigue las reglas de caché	Respuesta normal
404	10 segundos	Evitar cachear permanentemente páginas de error, lo que mantendría el 404 tras corregirlo
403/500/502	0	Los errores de servidor no se cachean, para facilitar una rápida recuperación

7. Automatización del script de publicación (subida + refresco automático)

Este proyecto ya incluye el script de publicación con un clic scripts/deploy.mjs, que completa todo el flujo de «construcción → subida incremental → refresco automático de la caché CDN».

7.1 Preparación del entorno

1. Instala las dependencias: npm i -D cos-nodejs-sdk-v5 tencentcloud-sdk-nodejs-cdn;
2. Crea una clave de API en CAM;
3. Copia .env.example como .env y rellénalo:

TENCENTCLOUD_SECRET_ID=your-secret-id
TENCENTCLOUD_SECRET_KEY=your-secret-key
COS_BUCKET=your-bucket-1250000000    # 含 appid 后缀
COS_REGION=ap-guangzhou              # 与存储桶地域一致
CDN_DOMAIN=docs.example.com          # 加速域名，设置后自动刷新 CDN

7.2 Uso

npm run deploy                  # 正式发布：构建 + 备份 + 上传 + 刷新 CDN
npm run deploy -- --dry-run     # 演练：只输出执行计划，不实际变更
npm run deploy -- --refresh-all # 改为整站目录刷新（默认只刷新 .html）
npm run deploy -- --skip-build  # 跳过构建，直接上传现有产物
npm run deploy -- --no-backup   # 跳过发布前版本备份

7.3 Flujo de ejecución del script

Paso	Operación	Descripción
1	npm run docs:build:all	Construir el sitio estático
2	Recopilar archivos locales	Calcular el MD5 de cada archivo
3	Listar objetos remotos	Obtener los archivos existentes de COS paginados (MD5 almacenado en una cabecera personalizada)
4	Calcular diferencias	Si el MD5 coincide, se omite; los archivos remotos eliminados localmente se limpian automáticamente
5	Respaldar la versión actual	Antes de publicar, hacer una instantánea del contenido en línea en __backup/<timestamp>/ (copia en el mismo bucket de COS, sin tráfico), conservando las últimas 10 versiones
6	Subida incremental	Solo se suben los archivos modificados; los HTML llevan Cache-Control: no-cache y los recursos estáticos 30 días
7	Refrescar CDN	Por defecto, refresco preciso de todas las URL .html (cuota suficiente); --refresh-all cambia al refresco por directorio de todo el sitio

¿Por qué solo refrescar HTML? Los nombres de archivo de los recursos estáticos llevan hash; si el contenido cambia, cambia el nombre del archivo y no hace falta refrescarlo. El HTML se cachea 10 minutos y, tras el refresco, se aplica de inmediato. Así, cada publicación solo necesita 10 cuotas de refresco.

7.4 Integración CI/CD (ejemplo con GitHub Actions)

name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', 'package.json']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build:all
      - name: 发布到 COS + 刷新 CDN
        run: node scripts/deploy.mjs --skip-build
        env:
          TENCENTCLOUD_SECRET_ID: ${{ secrets.TENCENTCLOUD_SECRET_ID }}
          TENCENTCLOUD_SECRET_KEY: ${{ secrets.TENCENTCLOUD_SECRET_KEY }}
          COS_BUCKET: ${{ secrets.COS_BUCKET }}
          COS_REGION: ap-guangzhou
          CDN_DOMAIN: ${{ secrets.CDN_DOMAIN }}

Tras configurar las claves anteriores en Settings → Secrets del repositorio, cada push que modifique docs/ se publicará automáticamente.

7.5 Copia de seguridad y rollback de versiones

Antes de publicar, el script guarda automáticamente una instantánea del contenido en línea actual bajo el prefijo __backup/<timestamp>/ (copia en el mismo bucket de COS, sin coste de tráfico), conservando las últimas 10 versiones. Si algo sale mal en la publicación, puedes hacer rollback en cualquier momento.

npm run rollback                            # 列出所有备份版本（时间 + 文件数）
npm run rollback -- --to 20260831103000     # 回滚到指定版本
npm run rollback -- --to 20260831103000 --prune    # 回滚并删除该版本之外的多余文件
npm run rollback -- --to 20260831103000 --dry-run  # 演练，只输出执行计划
npm run rollback -- --to 20260831103000 --refresh-all  # 回滚后整站刷新（默认只刷 .html）

Principio del rollback: se copian los objetos de la copia de seguridad de vuelta a la raíz del sitio (conservando las cabeceras de caché originales); con --prune se eliminan los archivos sobrantes actualmente en línea; después se refresca automáticamente la caché del CDN y el sitio se restaura de inmediato.

Diseño de seguridad

• La copia de seguridad se realiza antes de la subida; si la copia falla, se considera un riesgo para la publicación y primero hay que resolverlo antes de continuar;
• El rollback solo restaura los archivos de la copia de seguridad, sin tocar otras versiones de copia (no interfieren entre sí);
• --dry-run funciona totalmente sin conexión; se puede ensayar con claves falsas.

7.6 Generación automática del registro de cambios

Incluye scripts/changelog.mjs, que admite dos modos (detección automática del repositorio git):

npm run changelog                  # 打印最近 30 天更新日志
npm run changelog -- --days 7      # 只看最近 7 天
npm run changelog -- --write       # 写入 CHANGELOG.md
npm run changelog -- --from <ref>  # git 模式：从指定 ref（tag/hash/HEAD~10）开始
npm run changelog -- --files       # 强制文件模式（无需 git）

• Modo git (recomendado): basado en git log, clasifica automáticamente según Conventional Commit (feat→nuevo, fix→corrección, docs→documentación, perf→rendimiento, etc.);
• Modo archivos (degradación automática): cuando no hay repositorio git, escanea la fecha de modificación y el título de los archivos Markdown en docs/ y los agrupa por fecha.

Se recomienda combinarlo con el flujo de publicación: primero npm run changelog -- --write para actualizar el registro, y después npm run deploy para publicar.

7.7 Alternativa ligera: coscli + tccli (sin escribir código)

Si no quieres introducir el SDK de Node, también puedes usar las herramientas oficiales de línea de comandos de Tencent Cloud:

# 1. 安装 coscli（增量同步 + 删除多余文件）
curl -L https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin-amd64 -o /usr/local/bin/coscli
chmod +x /usr/local/bin/coscli
coscli config  # 按提示填写密钥

npm run docs:build:all
coscli sync ./docs/.vitepress/dist/ cos://your-bucket/ -r --delete --include ".*"

# 2. 安装 tccli 并刷新 CDN（腾讯云官方 CLI）
pip install tccli
tccli configure  # 配置密钥
tccli cdn PurgeUrlsCache --Urls '["https://docs.example.com/index.html"]' --Area mainland

Estimación de costes

Con un sitio de documentación típico como ejemplo (sitio de 100 MB, 10.000 visitas al mes, unos 2 GB de tráfico CDN):

Elemento de facturación	Precio unitario	Coste mensual estimado
Almacenamiento estándar de COS	0.118 CNY/GB/mes	Aprox. 0.01 CNY (cubierto por la cuota gratuita de nuevos usuarios)
Tarifa de solicitudes de COS	0.01 CNY/10.000	Aprox. 0.01 CNY
Tráfico CDN (tramo 0-2 TB)	0.21 CNY/GB	Aprox. 0.42 CNY
Tráfico de retorno al origen de CDN	0.15 CNY/GB	Aprox. 0 CNY (tasa de aciertos de caché superior al 99%)
Certificado HTTPS	Gratuito	0 CNY
Total	—	Aprox. 0.5 CNY/mes

Notas de costes

• Cuanto mayor es el tráfico, menor es el precio unitario del CDN: en el tramo 2-10 TB es 0.20 CNY/GB y en el tramo 10-50 TB es 0.18 CNY/GB;
• Puedes comprar paquetes de tráfico CDN para reducir aún más el precio unitario (suele haber promociones);
• El único coste adicional es el dominio (los sufijos habituales cuestan unos 20-60 CNY/año, con promociones frecuentes de 1 CNY el primer año para nuevos usuarios); el propio registro es gratuito;
• Si no haces el registro ICP, también puedes usar directamente el dominio de acceso predeterminado que incluye COS, pero no podrás usar un dominio personalizado y la bajada pública se factura a 0.5 CNY/GB, por lo que se recomienda la combinación registro + CDN.

---

Consejo

Además de Tencent Cloud COS + CDN, en el entorno nacional también puedes usar Alibaba Cloud OSS + CDN, Qiniu Cloud, Upyun y otros servicios de almacenamiento de objetos para alojar sitios estáticos, con costes y operaciones similares.