站点管理

目录结构

路径	用途
/www/mkdocs/learn.kirarin.xyz/docs/	文档源文件（Markdown）
/www/mkdocs/learn.kirarin.xyz/mkdocs.yml	站点与主题配置
/www/mkdocs/learn.kirarin.xyz/.venv/	Python 虚拟环境（MkDocs Material）
/www/mkdocs/learn.kirarin.xyz/deploy.sh	构建并发布脚本
/www/wwwroot/learn.kirarin.xyz/	网站根目录（Nginx 实际提供的内容，由脚本生成，请勿手工修改）

编辑内容与本地预览

cd /www/mkdocs/learn.kirarin.xyz
.venv/bin/mkdocs serve -a 127.0.0.1:8000

预览服务只监听本机 127.0.0.1:8000，不会占用公网端口、不影响线上站点；如需远程查看可用 SSH 隧道，看完按 Ctrl+C 退出。

发布到线上（手动）

/www/mkdocs/learn.kirarin.xyz/deploy.sh

脚本会重新构建站点并同步到 /www/wwwroot/learn.kirarin.xyz/，同时保留宝塔的 .user.ini 和证书验证目录。

Git 自动发布（GitHub Actions）

把改动推送到 GitHub 仓库的 main 分支，即可自动完成「云端构建 → SSH 上传 → 线上切换」：

git add -A
git commit -m "update docs"
git push

• 工作流文件：.github/workflows/deploy.yml；推送 docs/、mkdocs.yml、requirements.txt 的变更时触发，也可在 GitHub 的 Actions 页面手动运行。
• 服务器部署身份：deploy 用户（密钥登录），仅允许通过 sudo 执行 /usr/local/sbin/learn-site-deploy 这一个固定脚本，无法做其他 root 操作。
• 仓库需在 GitHub 的 Settings → Secrets and variables → Actions 配置 Secret：DEPLOY_SSH_KEY（部署私钥）。
• 发布记录见 GitHub 仓库的 Actions 页面；只有构建成功并上传完成后才会执行线上切换，失败不影响现有版本。
• 手动发布后记得把改动提交推送到 GitHub，保持仓库与线上一致。

在宝塔面板中管理

• 面板 → 网站 → learn.kirarin.xyz：可查看访问日志、错误日志，管理伪静态、SSL 等。
• 站点根目录：/www/wwwroot/learn.kirarin.xyz，日志：/www/wwwlogs/learn.kirarin.xyz.log。
• 不要删除网站根目录下的 .user.ini（宝塔防跨站文件）。

HTTPS 证书

• 证书文件：/www/server/panel/vhost/cert/learn.kirarin.xyz/（fullchain.pem、privkey.pem）。
• 由 acme.sh 申请，已配置自动续期（root 的 crontab）。
• 手动续期：

/root/.acme.sh/acme.sh --renew -d learn.kirarin.xyz --force

备份建议

• 源码目录 /www/mkdocs/learn.kirarin.xyz（文档源、配置）。
• 在宝塔面板「计划任务」中添加备份任务；本站为静态站点，恢复时重新执行一次 deploy.sh 即可。

升级主题

cd /www/mkdocs/learn.kirarin.xyz
.venv/bin/pip install -U mkdocs-material
.venv/bin/pip freeze | grep -i mkdocs > requirements.txt
./deploy.sh