Deployment

This page explains the blog’s release & deployment: how static output is hosted, the Vercel production deployment and test-domain flow, the four Docker build modes, and the “code changes vs content changes” release choice. The deployment chain depends on git submodules (themes/matery/ etc.), so commits need dual-repo commits (see section 6).

1. Deploying Static Output (any static host)

Purpose: Hexo generates pure static files; the public/ directory can be dropped on any static host (Nginx, GitHub Pages, Cloudflare Pages, OSS etc.) and go live directly.

npm run build      # hexo generate; output in public/
npm run clean      # hexo clean; clears public/ and cache

• Deploying = syncing public/: copy to the web server root and you’re done; where the domain points is decided by the hosting platform
• Root URL must match: url in _config.yml decides absolute links in canonical/sitemap/RSS — sync it when changing the hosting domain (see the Global Configuration chapter)
• This project uses Vercel in production (next section); the old GitHub Pages deployment is retired

2. Vercel Production Deployment

Purpose: production at https://blog.17lai.site. Vercel is linked to the GitHub repo github.com:appotry/hexo.git (main branch) — pushes trigger automatic builds, no manual trigger needed.

# push to hexo.git (production repo)
tools/cicd.sh -r "feature description"    # build + version bump + git tag + push

• The build runs on Vercel’s cloud (npm run build); output goes directly on CDN
• Don’t create a separate deployment repo besides the production one; testing uses the independent hexoback.git (next section)
• After release, run tools/tests/release-test.sh to verify production per the release rule (20 pages + comment sections + version consistency)

3. Test Domain Flow (hexoback → blog2.17lai.site)

Purpose: verify on the test domain before a real release, keeping broken changes off production. Vercel has a second project listening on hexoback.git (test repo), deployed to https://blog2.17lai.site.

# push the test repo (Vercel auto-deploys to the test domain)
tools/cicd.sh -t "description"        # push test repo (Vercel deploys test domain)

# run PWA smoke + interaction verification on the test domain
make test-pwa                  # 7-page SW smoke + interaction verification

Only push production after tests pass:

tools/cicd.sh -r "feature"        # official release (version bump + CDN + git tag)
tools/tests/release-test.sh    # 【release rule】full layout automated tests

The two repos are fully separate; testing never pollutes production. Small changes (content-only) can skip the test domain and push directly with -c.

4. Docker Build (four modes of tools/cicd.sh)

Purpose: tools/cicd.sh is the full CI/CD entry (proxy → version management → sub-repo sync → config injection → build → PWA version → deploy push), supporting four modes:

Docker test environment (same bloodstar/hexo:latest image as NAS production):

docker compose -f docker-compose.test.yml up -d
docker compose -f docker-compose.test.yml exec hexo bash
# inside the container: tools/cicd.sh -d   (local debug build)
exit
docker compose -f docker-compose.test.yml down

Direct local builds are equivalent: tools/test.sh build or npx hexo server -p 4100 (avoids the 4000 port conflict with the Docker preview).

5. Release Flow Selection (code vs content)

Core principle: code changes use -r, content changes use -c/-d.

How to decide:

git status --short themes/matery/   # changed → code change → -r
git status --short source/          # content only → -d / -c

-r reads tools/.VERSION, bumps it and creates a git tag; -c reuses the old version.

6. Dual-Repo Commits (submodules)

The theme lives in the submodule themes/matery/; after theme changes, commit in both repos:

# 1. commit the submodule
git -C themes/matery add <files>
git -C themes/matery commit -m "[✨] feat(scope): description"

# 2. commit the parent repo (updates the submodule pointer)
git add themes/matery
git commit -m "[🔧] chore: update matery submodule pointer"

Local commit convention: [emoji] type(scope): description (✨ feat / 🐛 fix / 📖 docs / 🔧 chore etc.), one commit per thing.

7. Open Graph Metadata (open_graph)

Purpose: generate Open Graph social-sharing metadata for pages (title, description, thumbnail shown when sharing to WeChat/Twitter/Facebook).

Config (theme config):

open_graph:
  enable: true
  twitter_card: summary_large_image   # Twitter card type
  twitter_id:                         # Twitter user ID
  twitter_site:                       # Twitter site @username
  google_plus:                        # Google+ profile
  fb_admins:                          # Facebook admin ID
  fb_app_id:                          # Facebook App ID

Notes: based on Hexo’s built-in open_graph helper; with enable: true, OG tags are auto-generated from post front-matter (title/description/cover) and read by social platforms when sharing.

8. Safe Redirect Page (safego)

Purpose: external-link redirect safety page — outbound links first pass through a notice page on this site instead of jumping directly (anti-phishing/anti-tracking).

Config (theme config):

safego:
  enable: false

Notes: with enable: true, outbound links go through a safety notice page first; the visitor confirms before leaving. Reference implementation: Fluid safe jump.

Appendix: Deployment Quick Reference