维护手册细则
范围：服务启停、日志、端口、域名、证书、Nginx、容器、Gitea、Webhook。
用户使用说明见 产品介绍.md；发版动作见 上线记录.md。
1. 服务与端口（参考）
| 组件 | 典型端口 | 说明 |
|---|---|---|
| Memos | 5230 | 容器映射 |
| Gitea HTTP | 3000 | 容器映射 |
| Gitea SSH | 2222 | 容器映射 |
| webhook（adnanh） | 9000 | 宿主机，勿对公网开放 |
| Nginx | 80 / 443 | 对外入口 |
域名示例：memos.*、git.*、notes.*（以实际为准）。
2. 容器启停
Podman 将 docker 换为 podman。
查看状态：docker ps / docker logs memos / docker logs gitea。
3. Gitea 配置
数据卷内配置常见路径：/data/gitea/gitea/conf/app.ini（随挂载而变）。
常用项：
[service] DISABLE_REGISTRATION = true：禁止自助注册[webhook] ALLOWED_HOST_LIST = private,loopback,external：允许 Webhook 打内网地址
修改后：docker restart gitea。
4. Nginx
- 配置修改后：
nginx -t && systemctl reload nginx（或nginx -s reload）。 - Memos 反代块建议含
client_max_body_size 20m;（或按需增大）。 - notes：静态
root指向 MkDocssite_dir；try_files与 SPA/静态站策略一致。
5. 证书（Let's Encrypt / Certbot）
- 新子域：补充 DNS A 记录后执行
certbot --nginx -d notes.<域名>等。 - 续期：通常由 certbot timer 处理；异常时
certbot renew --dry-run排查。
6. MkDocs 构建与日志
- 构建脚本：
/opt/rebuild-notes.sh（示例路径）。 - cron 兜底日志：
/var/log/mkdocs-build.log（路径以 crontab 为准）。 - Webhook 服务日志：
journalctl -u webhook-mkdocs -f。
7. Webhook（notes 构建链路）
7.1 服务
7.2 排错速查
| 现象 | 检查 |
|---|---|
| Gitea Delivery 连接超时 | URL 是否误用容器内 127.0.0.1；改用 host.docker.internal 或 bridge 网关 |
| 401/404 | 路径 /hooks/rebuild-mkdocs 与 hooks.json 中 id 是否一致 |
| 200 但页面未变 | rebuild-notes.sh 工作目录与 git pull 目标；Nginx root 是否指向 site_dir |
200 但 git pull 失败 |
systemd 是否设置 Environment=HOME=...；git config --global --add safe.directory 是否覆盖裸库与工作副本 |
| Material 长幅 MkDocs 2.0 告警 | NO_MKDOCS_2_WARNING=1 写入脚本或 service |
详情与根因案例：问题总览.md 序号 014、015；Memos / 宿主磁盘与白屏、502：016。
8. 阿里云
- 安全组：仅开放需对外暴露的端口（通常 80/443、22）；不要放行 9000 到公网。
- 带宽：上行影响手机 → Memos 大文件体验。
9. 磁盘与宿主日志（影响 Memos / Nginx）
- 根分区满：Memos SQLite 与子域静态资源易出现 写失败 / 半截响应（浏览器
ERR_CONTENT_LENGTH_MISMATCH）；容器反复退出后出现 502。 - 速查：
df -h /、df -i；大目录du -xh / --max-depth=1、du -xh /root/.pm2 --max-depth=2。 - PM2：关注
~/.pm2/pm2.log与~/.pm2/logs/*.log；可用truncate -s 0 <文件>紧急回收空间，长期建议pm2 install pm2-logrotate。 - journal：
journalctl --disk-usage；必要时journalctl --vacuum-size=…。 - 容器清理：
podman/docker system prune -a会删掉 已停止 的容器；若memos为Exited会先被删，需按数据卷docker/podman run重建。详见问题016。