デプロイと公開

本サイトは完全な静的サイトであり、ビルド成果物は任意の静的ホスティングプラットフォームにデプロイできます。

ビルド

bash

npm run docs:build:all

出力ディレクトリは docs/.vitepress/dist です。

ヒント：npm run docs:build は既定では簡体中文のみをビルドします（ビルド時に多言語バージョンをビルドするか確認されます）。完全な多言語サイトを公開する場合は npm run docs:build:all を、日常の開発では npm run docs:dev を使用してください。

方法 1：GitHub Pages

リポジトリの Settings → Pages でデプロイするブランチとディレクトリを選択；
または GitHub Actions で自動ビルド：

yaml

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

方法 2：Vercel / Netlify

Vercel を例に：

リポジトリをインポート；
ビルドコマンド：npm run docs:build:all；
出力ディレクトリ：docs/.vitepress/dist；
デプロイをクリックするだけで、プッシュのたびに自動デプロイとプレビューブランチに対応。

方法 3：Nginx

bash

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

Nginx 設定例：

nginx

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

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

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

カスタムドメインと HTTPS

ホスティングプラットフォームでカスタムドメインをバインド；
CNAME レコードをプラットフォームに向けて設定；
プラットフォームが自動的に HTTPS 証明書を発行・更新。

方法 4：腾讯云 COS + CDN

国内アクセスで体験が良く低コストな選択肢の一つ。オブジェクトストレージ + CDN アクセラレーションで、中国大陆（中国本土）のユーザーを対象としたサイトに適しています。

1. 準備

腾讯云アカウント（新規ユーザーは無料枠を取得可能。通常は標準ストレージ 10GB と一部のトラフィックが含まれ、有効期間は数ヶ月）；
备案済みドメイン（中国大陆の CDN アクセラレーションドメインを使用するには必ず ICP 备案（届出）の完了が必要。審査は約 1〜3 週間、無料）。

备案プロセスの詳細（腾讯云 ICP 备案）

前提条件

ドメインが実名認証済みであること（ドメイン登録事業者で実施、通常 1〜3 日で有効）；
腾讯云アカウントの実名認証が完了し、腾讯云サーバー/轻量应用服务器などの备案用クラウドリソースを保有していること（备案にはクラウドリソースのバインドが必須）；
サイトの内容は《非经营性互联网信息服务备案管理办法》に適合し、個人备案では営利性コンテンツを扱えない。

ステップ	操作	必要書類	想定時間
1. ドメインの確認	腾讯云备案コンソールにログインし、ドメインを入力。システムが备案タイプ（初回备案/接続备案など）を自動判別	备案対象ドメイン	即時
2. 資料の記入	主体情報（個人名/企業名、証書番号）とサービス情報（サイト名、ドメイン、サイト責任者、サービス内容）を記入し、証書写真と核验单をアップロード	身分証の両面、手持ち写真（アプリの顔認証）、サイト責任者の情報、核验单（自動生成）	準備次第
3. 腾讯云の一次審査	腾讯云が資料の真実性・完全性を審査	—	1〜2 営業日
4. SMS 検証	工信部が検証コードを発行。24 時間以内に工信部备案システムにログインして検証を完了	受信した SMS 検証コード	24 時間以内
5. 管局審査	現地の通信管理局が最終審査	—	最長 20 営業日
6. 备案完了	SMS/メール通知を受信し、备案号を取得	—	通知に準ずる

备案通過後、さらに 2 つのことを行う必要があります：

サイト下部に备案号を表示し、工信部备案システム https://beian.miit.gov.cn にハイパーリンクを張る。例：「粤ICP备2026000000号」；
公安备案の申請も推奨（备案通過後 30 日以内）。一部の省では必須。

备案の豆知識

個人の初回备案は通常 1〜2 週間で完了。各地の管局の処理効率は異なる；
备案期間中は COS のデフォルトドメインや海外ノードに先にデプロイし、备案通過後にカスタムドメインへ切り替えることも可能；
备案は無料サービス。有料代行には注意（代行は資料整理の指導のみ提供）。

2. ストレージバケットの作成

コンソールでオブジェクトストレージ COS に入り、ストレージバケットを作成；
リージョンは近い場所を選択（例：広州 ap-guangzhou）；
アクセス権限は**公有讀私有写（公開読み取り・非公開書き込み）**を選択；
「静的网站（静的ウェブサイト）」機能を有効化し、インデックスドキュメントに index.html、エラードキュメントに 404.html を設定。

3. ビルド成果物のアップロード

ビルド後、docs/.vitepress/dist ディレクトリをアップロードします：

bash

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. CDN アクセラレーションの接続

コンソールでコンテンツ配信ネットワーク CDN に入り、アクセラレーションドメインを追加；
アクセラレーション地域は**中国大陆（中国本土）**を選択（未备案なら中国香港/海外を選択、速度は普通）；
オリジンタイプはオブジェクトストレージ COS を選択し、作成したストレージバケットを選択；
ドメイン接続方式は CNAME を選択し、案内に従ってドメインサービス事業者で CNAME レコードを追加；
CNAME の有効化を待ち（約 10 分）、「回源跟随 301/302」と「Range 回源」を有効化。

5. HTTPS の設定

5.1 無料証明書の申請

コンソールで SSL 証明書に入り、「無料証明書の申請」を選択；
証明書タイプは DV（ドメイン型）を選択し、アクセラレーションドメインをバインド；
検証方式は自動 DNS 検証を選択（ドメインが腾讯云/托管解析済みならワンクリックで完了）、発行を待つ（数分から数時間）。

5.2 CDN での有効化

CDN の「域名管理 → HTTPS 配置」で発行済みの証明書をチェック；
「HTTP 强制跳转 HTTPS（HTTP を強制的に HTTPS へリダイレクト）」を有効化（推奨。リダイレクトのステータスコードは 301 を選択）；
有効化後、初回アクセス前に「刷新预热（リフレッシュとプリヒート）」でホームページの URL をプリヒートし、初回アクセス速度を向上。

課金の説明

DV 証明書は無料で、更新費用は不要（期限前にシステムが通知、再申請可能）；
注意：CDN の HTTPS リクエスト数は付加価値サービスで、0.04 元/万回で課金——ドキュメントサイトはリクエスト数が少なく（月間数十万回程度）、約数元で無視できる程度；完全にこの費用を発生させたくない場合は、「付加価値サービス」で HTTPS の課金項目をオフにできる（非推奨。暗号化が失われる）。

5.3 デプロイ結果の検証

bash

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

5.4 CNAME 設定の説明

CDN に接続すると、アクセラレーションドメインに .cdn.dnsv1.com で終わる CNAME レコードが割り当てられるため、DNS 解決サービス事業者で追加する必要があります：

レコードタイプ	ホストレコード	レコード値	TTL
CNAME	`docs`	`docs.example.com.cdn.dnsv1.com`	600

有効時間は通常 10 分〜1 時間（TTL による）；
設定ミス（A レコードに誤設定するなど）があるとドメインが CDN に解決されず、アクセスエラーになる；
検証：nslookup docs.example.com で CNAME ターゲットが返れば成功。

6. キャッシュ設定

静的ドキュメントサイトではリソースに長期キャッシュを設定することを推奨します（CDN ヒット率は 99%+ に達し、ほぼ回源トラフィックなし）。CDN コンソールの「域名管理 → 缓存配置」で操作します。

6.1 推奨キャッシュルール

優先度	マッチタイプ	内容	キャッシュ時間	説明
1	ファイル拡張子	`.html`	10 分	コンテンツ更新後できるだけ早く反映
2	ファイル拡張子	`.js` `.css`	30 日	VitePress のビルド成果物には hash が付くので、長期キャッシュしても安心
3	ファイル拡張子	`.png` `.jpg` `.svg` `.webp` `.ico`	30 日	画像の静的リソース
4	ファイル拡張子	`.woff` `.woff2` `.ttf`	30 日	フォントファイル
5	全ファイル	`*`	30 日	フォールバックルール

6.2 キャッシュヒットとヒット率

キャッシュにヒットすると、CDN はエッジノードの内容を直接返し、回源トラフィックは発生しない（0.15 元/GB の回源費用を節約）；
ヒット率はコンソールの「统计分析 → 命中率」で確認でき、ドキュメントサイトは通常 99% 以上で安定；
ヒット率が低い場合、「クエリ文字列を無視」が有効か確認：有効にすると page.html?ref=a と page.html?ref=b が同じキャッシュにヒット。

6.3 キャッシュのリフレッシュとプリヒート

リフレッシュ：コンテンツ更新後に実行し、エッジノードのキャッシュをクリア（URL リフレッシュはリアルタイム反映；ディレクトリリフレッシュは約 5 分）；
プリヒート：リソースを事前にエッジノードにキャッシュ。新バージョンの公開や大規模キャンペーン時、初回アクセスで回源しないようにするため；
コンソールのパス：「刷新预热」→ URL/ディレクトリを入力 → 送信；
自動化の方法：公開スクリプトで coscmd upload の後に CDN リフレッシュ API（DescribeCdnHosts / URL リフレッシュ API）を呼び出すか、COS のイベント通知でトリガー。

6.4 ブラウザキャッシュ（セカンダリキャッシュ）

CDN ノードキャッシュのほか、ブラウザ自体もリソースをキャッシュします。COS または CDN の「HTTP レスポンスヘッダー設定」で静的リソースに以下を追加できます：

http

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

6.5 ステータスコードキャッシュ

ステータスコード	推奨キャッシュ時間	説明
`200`	キャッシュルールに従う	正常なレスポンス
`404`	10 秒	エラーページを恒久キャッシュせず、修正後も 404 になるのを防ぐ
`403/500/502`	0	サーバーエラーはキャッシュせず、迅速な復旧を可能にする

7. 公開スクリプトの自動化（アップロード + 自動リフレッシュ）

本プロジェクトにはワンクリック公開スクリプト scripts/deploy.mjs が内蔵されており、「ビルド → 差分アップロード → CDN キャッシュの自動リフレッシュ」の全フローを実行します。

7.1 環境準備

依存関係をインストール：npm i -D cos-nodejs-sdk-v5 tencentcloud-sdk-nodejs-cdn；
アクセス管理 CAM で API キーを作成；
.env.example を .env にコピーして記入：

bash

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 使い方

bash

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 スクリプト実行フロー

ステップ	操作	説明
1	`npm run docs:build:all`	静的サイトをビルド
2	ローカルファイルを収集	各ファイルの MD5 を計算
3	リモートオブジェクトを一覧	ページングで COS の既存ファイルを取得（MD5 はカスタムヘッダーに保存）
4	差分を計算	MD5 が同じならスキップ；ローカルで削除されたリモートファイルは自動クリーンアップ
5	現在のバージョンをバックアップ	公開前にオンラインの内容を `__backup/<タイムスタンプ>/` にスナップショット（COS 同一バケット内コピーで、トラフィックゼロ）、直近 10 バージョンを保持
6	差分アップロード	変更されたファイルのみアップロード。HTML は `Cache-Control: no-cache`、静的リソースは 30 日
7	CDN リフレッシュ	デフォルトで全 `.html` URL を精密リフレッシュ（クォータ十分）；`--refresh-all` でサイト全体のディレクトリリフレッシュに切り替え

なぜ HTML だけリフレッシュするのか？ 静的リソースのファイル名には hash が付き、内容が変わればファイル名も変わるためリフレッシュは不要；HTML は 10 分キャッシュで、リフレッシュ後すぐ反映される。これにより毎回の公開は 10 件のリフレッシュクォータだけで済む。

7.4 CI/CD 統合（GitHub Actions の例）

yaml

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 }}

リポジトリの Settings → Secrets で上記のキーを設定後、docs/ の変更をプッシュするたびに自動公開されます。

7.5 バージョンバックアップとロールバック

公開前、スクリプトは現在のオンライン内容を __backup/<タイムスタンプ>/ プレフィックスにスナップショット（COS 同一バケット内コピーでトラフィック費用なし）、直近 10 バージョンを保持し、公開に問題があればいつでもロールバックできます。

bash

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）

ロールバックの原理：バックアップオブジェクトをサイトルートディレクトリにコピーして戻す（元のキャッシュヘッダーを保持）、--prune 時は現在のオンラインにある余分なファイルを削除し、その後 CDN キャッシュを自動リフレッシュしてサイトを即座に復旧。

セキュリティ設計

バックアップはアップロード前に完了し、バックアップ失敗は公開リスクとみなして、先に解決してから続行；
ロールバックはバックアップ内のファイルのみ復元し、他のバックアップバージョンには触れない（互いに影響しない）；
--dry-run は完全にオフラインで、ダミーキーで先にリハーサル可能。

7.6 更新ログの自動生成

scripts/changelog.mjs を内蔵しており、2 つのモードをサポート（git リポジトリを自動検出）：

bash

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）

git モード（推奨）：git log に基づき、Conventional Commit で自動分類（feat→追加、fix→修正、docs→ドキュメント、perf→性能など）；
ファイルモード（自動フォールバック）：git リポジトリがない場合、docs/ 配下の Markdown ファイルの変更時刻とタイトルをスキャンし、日付でグループ化して生成。

公開フローと組み合わせることを推奨：まず npm run changelog -- --write で更新ログを更新し、その後 npm run deploy で公開。

7.7 軽量な代替案：coscli + tccli（コーディング不要）

Node SDK を導入したくない場合は、腾讯云の公式コマンドラインツールも使用できます：

bash

# 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

コスト見積もり

典型的なドキュメントサイト（サイト 100MB、月間アクセス 1 万回、CDN トラフィック約 2GB）を例に：

課金項目	単価	月間コスト見積もり
COS 標準ストレージ	0.118 元/GB/月	約 0.01 元（新規ユーザーの無料枠でカバー）
COS リクエスト費	0.01 元/万回	約 0.01 元
CDN トラフィック（0〜2TB 段階）	0.21 元/GB	約 0.42 元
CDN 回源トラフィック	0.15 元/GB	約 0 元（キャッシュヒット率 99%+）
HTTPS 証明書	無料	0 元
合計	—	約 0.5 元/月

費用のヒント

トラフィックが多いほど CDN 単価は低くなる：2〜10TB 帯は 0.20 元/GB、10〜50TB 帯は 0.18 元/GB；
CDN トラフィックパックを購入して単価をさらに下げることも可能（プロモーションが多い）；
唯一の追加コストはドメイン（一般的なサフィックスは約 20〜60 元/年、新規ユーザーは初年度 1 元のキャンペーンが多い）、备案自体は無料；
未备案でも COS のデフォルトアクセスドメインを直接使えるが、カスタムドメインは使えず、外部へのダウンロードが 0.5 元/GB で課金されるため、备案 + CDN の組み合わせを推奨。

ヒント

国内環境では腾讯云 COS + CDN のほか、阿里云 OSS + CDN、七牛云、又拍云などのオブジェクトストレージでも静的サイトをホスティング可能。コストと操作は類似しています。

デプロイと公開 ​

ビルド ​

方法 1：GitHub Pages ​

方法 2：Vercel / Netlify ​

方法 3：Nginx ​

カスタムドメインと HTTPS ​

方法 4：腾讯云 COS + CDN ​

1. 準備 ​

备案プロセスの詳細（腾讯云 ICP 备案） ​

2. ストレージバケットの作成 ​

3. ビルド成果物のアップロード ​

4. CDN アクセラレーションの接続 ​

5. HTTPS の設定 ​

5.1 無料証明書の申請 ​

5.2 CDN での有効化 ​

5.3 デプロイ結果の検証 ​

5.4 CNAME 設定の説明 ​

6. キャッシュ設定 ​

6.1 推奨キャッシュルール ​

6.2 キャッシュヒットとヒット率 ​

6.3 キャッシュのリフレッシュとプリヒート ​

6.4 ブラウザキャッシュ（セカンダリキャッシュ） ​

6.5 ステータスコードキャッシュ ​

7. 公開スクリプトの自動化（アップロード + 自動リフレッシュ） ​

7.1 環境準備 ​

7.2 使い方 ​

7.3 スクリプト実行フロー ​

7.4 CI/CD 統合（GitHub Actions の例） ​

7.5 バージョンバックアップとロールバック ​

7.6 更新ログの自動生成 ​

7.7 軽量な代替案：coscli + tccli（コーディング不要） ​

コスト見積もり ​

デプロイと公開

ビルド

方法 1：GitHub Pages

方法 2：Vercel / Netlify

方法 3：Nginx

カスタムドメインと HTTPS

方法 4：腾讯云 COS + CDN

1. 準備

备案プロセスの詳細（腾讯云 ICP 备案）

2. ストレージバケットの作成

3. ビルド成果物のアップロード

4. CDN アクセラレーションの接続

5. HTTPS の設定

5.1 無料証明書の申請

5.2 CDN での有効化

5.3 デプロイ結果の検証

5.4 CNAME 設定の説明

6. キャッシュ設定

6.1 推奨キャッシュルール

6.2 キャッシュヒットとヒット率

6.3 キャッシュのリフレッシュとプリヒート

6.4 ブラウザキャッシュ（セカンダリキャッシュ）

6.5 ステータスコードキャッシュ

7. 公開スクリプトの自動化（アップロード + 自動リフレッシュ）

7.1 環境準備

7.2 使い方

7.3 スクリプト実行フロー

7.4 CI/CD 統合（GitHub Actions の例）

7.5 バージョンバックアップとロールバック

7.6 更新ログの自動生成

7.7 軽量な代替案：coscli + tccli（コーディング不要）

コスト見積もり