admin/mkdocs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

鏇存柊鏂囨。

Browse Source
This commit is contained in:
renjianbo
2026-01-12 18:37:17 +08:00
parent 6940347a3d
commit a9a9b54c26
10 changed files with 1237 additions and 334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
.obsidian/workspace.json vendored
View File

@@ -27,12 +27,12 @@
"state": {
"type": "markdown",
"state": {
"file": "docs/Obsidian笔记体系/MOCs/源码阅读地图.md",
"file": "docs/Obsidian/2026-01-05 个人文档管理.md",
"mode": "source",
"source": false
},
"icon": "lucide-file",
"title": "源码阅读地图"
"title": "2026-01-05 个人文档管理"
}
}
],
@@ -200,6 +200,23 @@
},
"active": "42dcaa0fed1f392a",
"lastOpenFiles": [
"更新部署脚本/部署脚本使用说明.md",
"更新部署脚本/deploy.sh",
"更新部署脚本/deploy.py",
"更新部署脚本/deploy.ps1",
"更新部署脚本/deploy_config.json",
"更新部署脚本",
"新建文件夹",
"部署脚本使用说明.md",
"deploy.py",
"deploy_config.json",
"deploy.bat",
"deploy.sh",
"docs/index.md",
"文档完善提示词模板.md",
"使用说明.md",
"test_lifecycle.md",
"docs/Obsidian笔记体系/MOCs/源码阅读地图.md",
"docs/Obsidian笔记体系/Daily/templates/每日模板.md",
"个人笔记体系.md",
"docs/Obsidian笔记体系/Archive/资源-历史会议记录/2023年会议记录示例.md",
@@ -209,11 +226,8 @@
"docs/Obsidian笔记体系/Archive/项目-旧版ROM适配/README.md",
"docs/Obsidian笔记体系/Archive/资源-历史会议记录/README.md",
"docs/Obsidian笔记体系/Archive/README.md",
"docs/Obsidian笔记体系/Config/自定义脚本/自动生成日报.js",
"docs/Obsidian笔记体系/Config/自定义脚本/源码链接生成器.py",
"docs/Obsidian笔记体系/Config/插件列表与配置.md",
"docs/Obsidian笔记体系/MOCs/高频问题索引.md",
"docs/Obsidian笔记体系/MOCs/源码阅读地图.md",
"docs/Obsidian笔记体系/MOCs/Android Framework知识体系图.md",
"docs/Obsidian笔记体系/Daily/2024-06-02.md",
"docs/Obsidian笔记体系/Daily/2024-06-01.md",
@@ -221,20 +235,6 @@
"docs/Obsidian笔记体系/Resources/论文/移动操作系统前沿/移动边缘计算研究.md",
"docs/Obsidian笔记体系/Resources/论文/移动操作系统前沿/README.md",
"docs/Obsidian笔记体系/Resources/论文/Android系统优化论文/Android内存管理优化.md",
"docs/Obsidian笔记体系/Resources/论文/Android系统优化论文/Android启动优化研究.md",
"docs/Obsidian笔记体系/Resources/论文/Android系统优化论文/README.md",
"docs/Obsidian笔记体系/Resources/论文/README.md",
"docs/Obsidian笔记体系/Resources/技术文章/官方文档笔记/Android性能优化指南.md",
"docs/Obsidian笔记体系/Resources/技术文章/官方文档笔记/README.md",
"docs/Obsidian笔记体系/Resources/技术文章/内核相关文章/Binder内核机制分析.md",
"docs/Obsidian笔记体系/Resources/技术文章/内核相关文章/README.md",
"docs/Obsidian笔记体系/Resources/工具/脚本库/log_analyzer.py",
"docs/Obsidian笔记体系/Resources/工具/脚本库/performance_monitor.sh",
"docs/Obsidian笔记体系/Resources/工具/脚本库/test_startup_time.sh",
"docs/Obsidian笔记体系/脚本库/performance_monitor.sh",
"docs/Obsidian笔记体系/脚本库",
"docs/Obsidian笔记体系/Resources/工具/脚本库/collect_logs.sh",
"docs/Obsidian笔记体系/Resources/工具/脚本库/install_apks.sh",
"docs/Obsidian笔记体系/Areas/01-系统启动流程/Bootloader到Init.md.bak"
"docs/Obsidian笔记体系/Resources/论文/Android系统优化论文/Android启动优化研究.md"
]
}

110
deploy.bat Normal file
View File

@@ -0,0 +1,110 @@
@echo off
REM 自动化部署脚本 (Windows批处理版本)
REM 功能：更新mkdocs.yml -> Git提交推送 -> 服务器拉取并重启
setlocal enabledelayedexpansion
REM 配置参数
set "COMMIT_MESSAGE=%~1"
if "%COMMIT_MESSAGE%"=="" set "COMMIT_MESSAGE=更新文档"
set "SERVER_USER=%~2"
set "SERVER_HOST=%~3"
set "SERVER_PATH=%~4"
if "%SERVER_PATH%"=="" set "SERVER_PATH=~/devops/mkdocs"
echo =========================================
echo 步骤1: 更新mkdocs.yml
echo =========================================
python .\add_docs_to_mkdocs.py
if errorlevel 1 (
echo [错误] 更新mkdocs.yml失败
exit /b 1
)
echo [成功] mkdocs.yml更新成功
REM 检查是否有变更
echo.
echo 检查Git状态...
git status --porcelain >nul 2>&1
if errorlevel 1 (
echo 没有文件变更，跳过Git操作
exit /b 0
)
echo 发现以下变更:
git status --short
echo.
echo =========================================
echo 步骤2: Git提交和推送
echo =========================================
REM 添加所有变更
echo 添加文件到Git...
git add .
if errorlevel 1 (
echo [错误] Git add 失败
exit /b 1
)
echo [成功] 文件已添加到暂存区
REM 提交
echo 提交变更...
git commit -m "%COMMIT_MESSAGE%"
if errorlevel 1 (
echo [错误] Git commit 失败
exit /b 1
)
echo [成功] 变更已提交
REM 推送
echo 推送到远程仓库...
git push origin master
if errorlevel 1 (
echo [错误] Git push 失败
exit /b 1
)
echo [成功] 代码已推送到远程仓库
REM 步骤3: 服务器操作
if not "%SERVER_USER%"=="" if not "%SERVER_HOST%"=="" (
echo.
echo =========================================
echo 步骤3: 服务器拉取代码并重启服务
echo =========================================
echo 连接到服务器: %SERVER_USER%@%SERVER_HOST%
echo 执行命令: cd %SERVER_PATH% ^&^& git pull origin master ^&^& docker-compose restart
ssh %SERVER_USER%@%SERVER_HOST% "cd %SERVER_PATH% && git pull origin master && docker-compose restart"
if errorlevel 1 (
echo [错误] 服务器操作失败
echo [提示] 请确保已配置SSH密钥，或手动执行服务器命令
exit /b 1
)
echo [成功] 服务器代码已更新，服务已重启
) else (
echo.
echo =========================================
echo 步骤3: 服务器操作（跳过）
echo =========================================
echo 未配置服务器信息，跳过服务器操作
echo.
echo 使用方法:
echo deploy.bat [提交信息] [服务器用户] [服务器地址] [服务器路径]
echo.
echo 示例:
echo deploy.bat "更新文档" user example.com ~/devops/mkdocs
echo.
echo 或手动执行:
echo ssh user@host "cd ~/devops/mkdocs ^&^& git pull origin master ^&^& docker-compose restart"
)
echo.
echo =========================================
echo [成功] 部署完成！
echo =========================================
endlocal

132
docs/index.md
View File

@@ -1,66 +1,66 @@
# 欢迎来到个人知识库
这是一个基于 MkDocs Material 的个人技术文档和知识管理平台。
## 📚 功能特性
- 📝 **Markdown 支持**: 使用 Markdown 编写文档，简单易用
- 🎨 **Material 主题**: 美观现代的 Material Design 界面
- 🔍 **全文搜索**: 快速查找所需内容
- 📱 **响应式设计**: 支持各种设备访问
- 🌙 **深色模式**: 支持浅色/深色主题切换
- 📊 **代码高亮**: 支持多种编程语言的语法高亮
- 🔗 **导航系统**: 清晰的文档导航结构
## 🚀 快速开始
### 编辑文档
1. 在 `docs/` 目录下创建或编辑 Markdown 文件
2. 在 `mkdocs.yml` 中更新导航配置
3. 保存后，MkDocs 会自动重新加载（开发模式）
### 添加新文档
1. 在 `docs/` 目录下创建新的 `.md` 文件
2. 在 `mkdocs.yml` 的 `nav` 部分添加导航项
3. 重启服务或等待自动重载
### 构建静态站点
```bash
# 进入容器执行构建
docker exec -it mkdocs mkdocs build
# 或使用 docker-compose
docker-compose exec mkdocs mkdocs build
```
## 📖 文档结构
```
docs/
├── index.md # 首页
├── 开发指南/ # 开发相关文档
├── DevOps平台/ # DevOps 工具使用指南
├── 技术文档/ # 技术架构和 API 文档
└── 学习笔记/ # 学习笔记和总结
```
## 🔗 相关链接
- [MkDocs 官方文档](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [Markdown 语法指南](https://www.markdownguide.org/)
## 💡 使用技巧
1. **代码块**: 使用三个反引号包裹代码，并指定语言
2. **表格**: 使用 Markdown 表格语法
3. **图片**: 将图片放在 `docs/images/` 目录，使用相对路径引用
4. **数学公式**: 支持 LaTeX 数学公式（需要启用相应插件）
5. **流程图**: 支持 Mermaid 流程图（已配置）
---
**开始编写你的文档吧！** 📝
# 欢迎来到个人知识库
这是一个基于 MkDocs Material 的个人技术文档和知识管理平台。
## 📚 功能特性
- 📝 **Markdown 支持**: 使用 Markdown 编写文档，简单易用
- 🎨 **Material 主题**: 美观现代的 Material Design 界面
- 🔍 **全文搜索**: 快速查找所需内容
- 📱 **响应式设计**: 支持各种设备访问
- 🌙 **深色模式**: 支持浅色/深色主题切换
- 📊 **代码高亮**: 支持多种编程语言的语法高亮
- 🔗 **导航系统**: 清晰的文档导航结构
## 🚀 快速开始
### 编辑文档
1. 在 `docs/` 目录下创建或编辑 Markdown 文件
2. 在 `mkdocs.yml` 中更新导航配置
3. 保存后，MkDocs 会自动重新加载（开发模式）
### 添加新文档
1. 在 `docs/` 目录下创建新的 `.md` 文件
2. 在 `mkdocs.yml` 的 `nav` 部分添加导航项
3. 重启服务或等待自动重载
### 构建静态站点
```bash
# 进入容器执行构建
docker exec -it mkdocs mkdocs build
# 或使用 docker-compose
docker-compose exec mkdocs mkdocs build
```
## 📖 文档结构
```
docs/
├── index.md # 首页
├── 开发指南/ # 开发相关文档
├── DevOps平台/ # DevOps 工具使用指南
├── 技术文档/ # 技术架构和 API 文档
└── 学习笔记/ # 学习笔记和总结
```
## 🔗 相关链接
- [MkDocs 官方文档](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [Markdown 语法指南](https://www.markdownguide.org/)
## 💡 使用技巧
1. **代码块**: 使用三个反引号包裹代码，并指定语言
2. **表格**: 使用 Markdown 表格语法
3. **图片**: 将图片放在 `docs/images/` 目录，使用相对路径引用
4. **数学公式**: 支持 LaTeX 数学公式（需要启用相应插件）
5. **流程图**: 支持 Mermaid 流程图（已配置）
---
**开始编写你的文档吧！** 📝

29
mkdocs.yml
View File

@@ -165,6 +165,35 @@ nav:
- Obsidian笔记体系/Templates/技术方案设计模板.md
- Obsidian笔记体系/Templates/源码解析模板.md
- Obsidian笔记体系/Templates/问题排查模板.md
- Obsidian笔记体系/Archive/README.md
- Obsidian笔记体系/Archive/资源-历史会议记录/2023年会议记录示例.md
- Obsidian笔记体系/Archive/资源-历史会议记录/README.md
- Obsidian笔记体系/Archive/项目-旧版ROM适配/README.md
- Obsidian笔记体系/Archive/项目-旧版ROM适配/项目A-旧版ROM适配-README.md
- Obsidian笔记体系/Archive/领域-已废弃API研究/README.md
- Obsidian笔记体系/Archive/领域-已废弃API研究/已废弃API-旧版Activity启动方式.md
- Obsidian笔记体系/Resources/会议与分享/Android开发者峰会笔记/Google_IO_2024_性能优化.md
- Obsidian笔记体系/Resources/会议与分享/Android开发者峰会笔记/README.md
- Obsidian笔记体系/Resources/会议与分享/README.md
- Obsidian笔记体系/Resources/会议与分享/内部技术分享记录/Activity启动流程优化分享.md
- Obsidian笔记体系/Resources/会议与分享/内部技术分享记录/README.md
- Obsidian笔记体系/Resources/会议与分享/内部技术分享记录/代码评审模板示例.md
- Obsidian笔记体系/Resources/工具/效率工具推荐/README.md
- Obsidian笔记体系/Resources/工具/脚本库/README.md
- Obsidian笔记体系/Resources/技术文章/README.md
- Obsidian笔记体系/Resources/技术文章/优质博客归档（Gityuan等）/Gityuan_Activity启动流程.md
- Obsidian笔记体系/Resources/技术文章/优质博客归档（Gityuan等）/README.md
- Obsidian笔记体系/Resources/技术文章/内核相关文章/Binder内核机制分析.md
- Obsidian笔记体系/Resources/技术文章/内核相关文章/README.md
- Obsidian笔记体系/Resources/技术文章/官方文档笔记/Android性能优化指南.md
- Obsidian笔记体系/Resources/技术文章/官方文档笔记/README.md
- Obsidian笔记体系/Resources/论文/Android系统优化论文/Android内存管理优化.md
- Obsidian笔记体系/Resources/论文/Android系统优化论文/Android启动优化研究.md
- Obsidian笔记体系/Resources/论文/Android系统优化论文/README.md
- Obsidian笔记体系/Resources/论文/README.md
- Obsidian笔记体系/Resources/论文/移动操作系统前沿/README.md
- Obsidian笔记体系/Resources/论文/移动操作系统前沿/移动系统安全研究.md
- Obsidian笔记体系/Resources/论文/移动操作系统前沿/移动边缘计算研究.md
markdown_extensions:
- pymdownx.highlight:

496
使用说明.md
View File

@@ -1,248 +1,248 @@
# MkDocs 使用说明
## 📝 编辑方式说明
### ❌ 不支持在线编辑
**MkDocs 是一个静态文档生成工具，前端网站只能查看，不能在线编辑。**
### ✅ 正确的使用方式
**需要编辑 Markdown 文件并放入对应目录，MkDocs 会自动生成网站。**
## 🔄 工作流程
```
编辑 Markdown 文件 → 保存文件 → MkDocs 自动检测变化 → 重新生成网站 → 浏览器自动刷新
```
## 📖 详细使用步骤
### 方式一：在服务器上直接编辑（推荐用于快速修改）
1. **SSH 连接到服务器**
```bash
ssh renjianbo@101.43.95.130
```
2. **编辑文档文件**
```bash
# 使用 vim 编辑
vim /home/renjianbo/devops/mkdocs/docs/index.md
# 或使用 nano
nano /home/renjianbo/devops/mkdocs/docs/index.md
```
3. **保存文件后，MkDocs 会自动重新加载**（开发模式）
- 无需重启服务
- 浏览器刷新即可看到更新
### 方式二：本地开发后上传（推荐用于大量编辑）
1. **在本地电脑上编辑**
- 使用你喜欢的编辑器（VS Code、Typora、MarkText 等）
- 编辑 `docs/` 目录下的 Markdown 文件
2. **上传到服务器**
```bash
# 使用 scp 上传
scp -r docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/
# 或使用 rsync 同步
rsync -avz docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/docs/
```
3. **MkDocs 会自动检测变化并更新**
### 方式三：使用 Git 管理（推荐用于团队协作）
1. **在本地编辑并提交到 Git**
```bash
cd /home/renjianbo/devops/mkdocs
git add .
git commit -m "更新文档"
git push
```
2. **在服务器上拉取更新**
```bash
ssh renjianbo@101.43.95.130
cd /home/renjianbo/devops/mkdocs
git pull
```
3. **MkDocs 会自动更新**
## 📁 文件组织
### 目录结构
```
docs/
├── index.md # 首页
├── 开发指南/
│ ├── 快速开始.md
│ ├── 项目结构.md
│ └── 开发规范.md
├── DevOps平台/
│ ├── Gerrit使用指南.md
│ ├── Gitea使用指南.md
│ └── ...
├── 技术文档/
│ ├── 架构设计.md
│ └── ...
└── 学习笔记/
├── Java学习.md
└── ...
```
### 添加新文档
1. **创建 Markdown 文件**
```bash
# 例如：添加新的学习笔记
touch /home/renjianbo/devops/mkdocs/docs/学习笔记/新主题.md
```
2. **编辑文件内容**
```markdown
# 新主题
这是新主题的内容...
```
3. **在 mkdocs.yml 中添加导航**
```yaml
nav:
- 学习笔记:
- 学习笔记/Java学习.md
- 学习笔记/前端学习.md
- 学习笔记/新主题.md # 添加这一行
```
4. **保存后自动生效**
## 🛠️ 常用编辑命令
### 查看现有文档
```bash
ls -la /home/renjianbo/devops/mkdocs/docs/
```
### 编辑文档
```bash
# 使用 vim
vim /home/renjianbo/devops/mkdocs/docs/index.md
# 使用 nano（更简单）
nano /home/renjianbo/devops/mkdocs/docs/index.md
```
### 创建新文档
```bash
# 创建新文件
touch /home/renjianbo/devops/mkdocs/docs/新文档.md
# 或直接编辑（如果不存在会自动创建）
nano /home/renjianbo/devops/mkdocs/docs/新文档.md
```
### 查看 MkDocs 日志（确认更新）
```bash
docker logs -f mkdocs
```
## 💡 编辑技巧
### 1. 使用本地编辑器（推荐）
在本地使用专业的 Markdown 编辑器：
- **VS Code** + Markdown 插件
- **Typora**（所见即所得）
- **MarkText**（开源免费）
### 2. 实时预览
MkDocs 开发模式支持自动刷新：
- 编辑文件并保存
- 浏览器会自动刷新显示最新内容
- 无需手动重启服务
### 3. 文件同步
如果需要在多台电脑上编辑：
- 使用 Git 管理文档
- 或使用 rsync/scp 同步文件
## 🔍 验证更新
编辑文件后，可以通过以下方式验证：
1. **查看容器日志**
```bash
docker logs mkdocs | tail -20
```
应该看到类似信息：
```
INFO - Documentation built in 1.32 seconds
INFO - [时间] Serving on http://0.0.0.0:8000/
```
2. **刷新浏览器**
- 访问 http://101.43.95.130:8000
- 按 F5 或 Ctrl+R 刷新
- 应该看到最新内容
## ❓ 常见问题
### Q: 为什么不能在前端网站直接编辑？
A: MkDocs 是静态文档生成工具，它读取 Markdown 文件并生成静态 HTML 网站。前端只是展示，不提供编辑功能。
### Q: 如果我想在线编辑怎么办？
A: 可以考虑以下方案：
1. **使用 Wiki 系统**（如 Gitea 的 Wiki 功能）
2. **使用在线 Markdown 编辑器**（如 HackMD、StackEdit）
3. **使用 Git 工作流**（本地编辑 → Git 提交 → 服务器拉取）
### Q: 编辑后多久能看到更新？
A: 在开发模式下，保存文件后几秒钟内就会自动更新，刷新浏览器即可看到。
### Q: 需要重启服务吗？
A: 不需要！MkDocs 开发模式会自动检测文件变化并重新生成网站。
## 📚 相关资源
- [Markdown 语法指南](https://www.markdownguide.org/)
- [MkDocs 官方文档](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
---
**总结：MkDocs 需要编辑 Markdown 文件，不能在前端网站直接编辑。编辑文件后，MkDocs 会自动生成更新的网站。**
# MkDocs 使用说明
## 📝 编辑方式说明
### ❌ 不支持在线编辑
**MkDocs 是一个静态文档生成工具，前端网站只能查看，不能在线编辑。**
### ✅ 正确的使用方式
**需要编辑 Markdown 文件并放入对应目录，MkDocs 会自动生成网站。**
## 🔄 工作流程
```
编辑 Markdown 文件 → 保存文件 → MkDocs 自动检测变化 → 重新生成网站 → 浏览器自动刷新
```
## 📖 详细使用步骤
### 方式一：在服务器上直接编辑（推荐用于快速修改）
1. **SSH 连接到服务器**
```bash
ssh renjianbo@101.43.95.130
```
2. **编辑文档文件**
```bash
# 使用 vim 编辑
vim /home/renjianbo/devops/mkdocs/docs/index.md
# 或使用 nano
nano /home/renjianbo/devops/mkdocs/docs/index.md
```
3. **保存文件后，MkDocs 会自动重新加载**（开发模式）
- 无需重启服务
- 浏览器刷新即可看到更新
### 方式二：本地开发后上传（推荐用于大量编辑）
1. **在本地电脑上编辑**
- 使用你喜欢的编辑器（VS Code、Typora、MarkText 等）
- 编辑 `docs/` 目录下的 Markdown 文件
2. **上传到服务器**
```bash
# 使用 scp 上传
scp -r docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/
# 或使用 rsync 同步
rsync -avz docs/ renjianbo@101.43.95.130:/home/renjianbo/devops/mkdocs/docs/
```
3. **MkDocs 会自动检测变化并更新**
### 方式三：使用 Git 管理（推荐用于团队协作）
1. **在本地编辑并提交到 Git**
```bash
cd /home/renjianbo/devops/mkdocs
git add .
git commit -m "更新文档"
git push
```
2. **在服务器上拉取更新**
```bash
ssh renjianbo@101.43.95.130
cd /home/renjianbo/devops/mkdocs
git pull
```
3. **MkDocs 会自动更新**
## 📁 文件组织
### 目录结构
```
docs/
├── index.md # 首页
├── 开发指南/
│ ├── 快速开始.md
│ ├── 项目结构.md
│ └── 开发规范.md
├── DevOps平台/
│ ├── Gerrit使用指南.md
│ ├── Gitea使用指南.md
│ └── ...
├── 技术文档/
│ ├── 架构设计.md
│ └── ...
└── 学习笔记/
├── Java学习.md
└── ...
```
### 添加新文档
1. **创建 Markdown 文件**
```bash
# 例如：添加新的学习笔记
touch /home/renjianbo/devops/mkdocs/docs/学习笔记/新主题.md
```
2. **编辑文件内容**
```markdown
# 新主题
这是新主题的内容...
```
3. **在 mkdocs.yml 中添加导航**
```yaml
nav:
- 学习笔记:
- 学习笔记/Java学习.md
- 学习笔记/前端学习.md
- 学习笔记/新主题.md # 添加这一行
```
4. **保存后自动生效**
## 🛠️ 常用编辑命令
### 查看现有文档
```bash
ls -la /home/renjianbo/devops/mkdocs/docs/
```
### 编辑文档
```bash
# 使用 vim
vim /home/renjianbo/devops/mkdocs/docs/index.md
# 使用 nano（更简单）
nano /home/renjianbo/devops/mkdocs/docs/index.md
```
### 创建新文档
```bash
# 创建新文件
touch /home/renjianbo/devops/mkdocs/docs/新文档.md
# 或直接编辑（如果不存在会自动创建）
nano /home/renjianbo/devops/mkdocs/docs/新文档.md
```
### 查看 MkDocs 日志（确认更新）
```bash
docker logs -f mkdocs
```
## 💡 编辑技巧
### 1. 使用本地编辑器（推荐）
在本地使用专业的 Markdown 编辑器：
- **VS Code** + Markdown 插件
- **Typora**（所见即所得）
- **MarkText**（开源免费）
### 2. 实时预览
MkDocs 开发模式支持自动刷新：
- 编辑文件并保存
- 浏览器会自动刷新显示最新内容
- 无需手动重启服务
### 3. 文件同步
如果需要在多台电脑上编辑：
- 使用 Git 管理文档
- 或使用 rsync/scp 同步文件
## 🔍 验证更新
编辑文件后，可以通过以下方式验证：
1. **查看容器日志**
```bash
docker logs mkdocs | tail -20
```
应该看到类似信息：
```
INFO - Documentation built in 1.32 seconds
INFO - [时间] Serving on http://0.0.0.0:8000/
```
2. **刷新浏览器**
- 访问 http://101.43.95.130:8000
- 按 F5 或 Ctrl+R 刷新
- 应该看到最新内容
## ❓ 常见问题
### Q: 为什么不能在前端网站直接编辑？
A: MkDocs 是静态文档生成工具，它读取 Markdown 文件并生成静态 HTML 网站。前端只是展示，不提供编辑功能。
### Q: 如果我想在线编辑怎么办？
A: 可以考虑以下方案：
1. **使用 Wiki 系统**（如 Gitea 的 Wiki 功能）
2. **使用在线 Markdown 编辑器**（如 HackMD、StackEdit）
3. **使用 Git 工作流**（本地编辑 → Git 提交 → 服务器拉取）
### Q: 编辑后多久能看到更新？
A: 在开发模式下，保存文件后几秒钟内就会自动更新，刷新浏览器即可看到。
### Q: 需要重启服务吗？
A: 不需要！MkDocs 开发模式会自动检测文件变化并重新生成网站。
## 📚 相关资源
- [Markdown 语法指南](https://www.markdownguide.org/)
- [MkDocs 官方文档](https://www.mkdocs.org/)
- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
---
**总结：MkDocs 需要编辑 Markdown 文件，不能在前端网站直接编辑。编辑文件后，MkDocs 会自动生成更新的网站。**

128
更新部署脚本/deploy.ps1 Normal file
View File

@@ -0,0 +1,128 @@
# 自动化部署脚本
# 功能：更新mkdocs.yml -> Git提交推送 -> 服务器拉取并重启
param(
[string]$CommitMessage = "更新文档",
[string]$ServerUser = "",
[string]$ServerHost = "",
[string]$ServerPath = "~/devops/mkdocs"
)
# 颜色输出函数
function Write-ColorOutput($ForegroundColor) {
$fc = $host.UI.RawUI.ForegroundColor
$host.UI.RawUI.ForegroundColor = $ForegroundColor
if ($args) {
Write-Output $args
}
$host.UI.RawUI.ForegroundColor = $fc
}
function Write-Success { Write-ColorOutput Green $args }
function Write-Error { Write-ColorOutput Red $args }
function Write-Info { Write-ColorOutput Cyan $args }
# 步骤1: 更新mkdocs.yml
Write-Info "========================================="
Write-Info "步骤1: 更新mkdocs.yml"
Write-Info "========================================="
try {
python .\add_docs_to_mkdocs.py
if ($LASTEXITCODE -ne 0) {
Write-Error "更新mkdocs.yml失败，退出码: $LASTEXITCODE"
exit 1
}
Write-Success "✓ mkdocs.yml更新成功"
} catch {
Write-Error "执行Python脚本时出错: $_"
exit 1
}
# 检查是否有变更
Write-Info "`n检查Git状态..."
$gitStatus = git status --porcelain
if (-not $gitStatus) {
Write-Info "没有文件变更，跳过Git操作"
exit 0
}
Write-Info "发现以下变更:"
git status --short
# 步骤2: Git操作
Write-Info "`n========================================="
Write-Info "步骤2: Git提交和推送"
Write-Info "========================================="
try {
# 添加所有变更
Write-Info "添加文件到Git..."
git add .
if ($LASTEXITCODE -ne 0) {
Write-Error "Git add 失败"
exit 1
}
Write-Success "✓ 文件已添加到暂存区"
# 提交
Write-Info "提交变更..."
git commit -m $CommitMessage
if ($LASTEXITCODE -ne 0) {
Write-Error "Git commit 失败"
exit 1
}
Write-Success "✓ 变更已提交"
# 推送
Write-Info "推送到远程仓库..."
git push origin master
if ($LASTEXITCODE -ne 0) {
Write-Error "Git push 失败"
exit 1
}
Write-Success "✓ 代码已推送到远程仓库"
} catch {
Write-Error "Git操作时出错: $_"
exit 1
}
# 步骤3: 服务器操作
if ($ServerUser -and $ServerHost) {
Write-Info "`n========================================="
Write-Info "步骤3: 服务器拉取代码并重启服务"
Write-Info "========================================="
Write-Info "连接到服务器: $ServerUser@$ServerHost"
Write-Info "执行命令: cd $ServerPath && git pull origin master && docker-compose restart"
try {
# 使用SSH执行远程命令
$remoteCommand = "cd $ServerPath && git pull origin master && docker-compose restart"
ssh "${ServerUser}@${ServerHost}" $remoteCommand
if ($LASTEXITCODE -ne 0) {
Write-Error "服务器操作失败，退出码: $LASTEXITCODE"
exit 1
}
Write-Success "✓ 服务器代码已更新，服务已重启"
} catch {
Write-Error "SSH连接或执行命令时出错: $_"
Write-Info "提示: 请确保已配置SSH密钥，或手动执行服务器命令"
exit 1
}
} else {
Write-Info "`n========================================="
Write-Info "步骤3: 服务器操作（跳过）"
Write-Info "========================================="
Write-Info "未配置服务器信息，跳过服务器操作"
Write-Info "如需配置，请使用参数:"
Write-Info " -ServerUser <用户名>"
Write-Info " -ServerHost <服务器地址>"
Write-Info " -ServerPath <服务器路径>"
Write-Info "`n或手动执行:"
Write-Info " ssh user@host 'cd ~/devops/mkdocs && git pull origin master && docker-compose restart'"
}
Write-Info "`n========================================="
Write-Success "部署完成！"
Write-Info "========================================="

252
更新部署脚本/deploy.py Normal file
View File

@@ -0,0 +1,252 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
自动化部署脚本
功能：更新mkdocs.yml -> Git提交推送 -> 服务器拉取并重启
"""
import os
import sys
import json
import subprocess
import argparse
from pathlib import Path
# 颜色输出
class Colors:
RED = '\033[91m'
GREEN = '\033[92m'
YELLOW = '\033[93m'
CYAN = '\033[96m'
RESET = '\033[0m'
def print_info(msg):
print(f"{Colors.CYAN}{msg}{Colors.RESET}")
def print_success(msg):
print(f"{Colors.GREEN}✓ {msg}{Colors.RESET}")
def print_error(msg):
print(f"{Colors.RED}✗ {msg}{Colors.RESET}")
def print_warning(msg):
print(f"{Colors.YELLOW}⚠ {msg}{Colors.RESET}")
def run_command(cmd, check=True, shell=False):
"""执行命令"""
try:
if isinstance(cmd, str):
cmd = cmd.split()
result = subprocess.run(
cmd,
check=check,
shell=shell,
capture_output=True,
text=True,
encoding='utf-8'
)
return result.returncode == 0, result.stdout, result.stderr
except subprocess.CalledProcessError as e:
return False, e.stdout, e.stderr
except Exception as e:
return False, "", str(e)
def load_config():
"""加载配置文件"""
config_file = Path("deploy_config.json")
if config_file.exists():
try:
with open(config_file, 'r', encoding='utf-8') as f:
return json.load(f)
except Exception as e:
print_warning(f"加载配置文件失败: {e}")
return {}
def step1_update_mkdocs(script_path="add_docs_to_mkdocs.py"):
"""步骤1: 更新mkdocs.yml"""
print_info("=" * 50)
print_info("步骤1: 更新mkdocs.yml")
print_info("=" * 50)
if not Path(script_path).exists():
print_error(f"找不到脚本: {script_path}")
return False
success, stdout, stderr = run_command([sys.executable, script_path])
if success:
print_success("mkdocs.yml更新成功")
if stdout:
print(stdout)
return True
else:
print_error("更新mkdocs.yml失败")
if stderr:
print_error(stderr)
return False
def step2_git_operations(commit_message, branch="master", remote="origin"):
"""步骤2: Git操作"""
print_info("")
print_info("=" * 50)
print_info("步骤2: Git提交和推送")
print_info("=" * 50)
# 检查是否有变更
print_info("检查Git状态...")
success, stdout, _ = run_command(["git", "status", "--porcelain"])
if not stdout.strip():
print_info("没有文件变更，跳过Git操作")
return True
print_info("发现以下变更:")
success, stdout, _ = run_command(["git", "status", "--short"])
print(stdout)
# 添加文件
print_info("添加文件到Git...")
success, _, stderr = run_command(["git", "add", "."])
if not success:
print_error("Git add 失败")
if stderr:
print_error(stderr)
return False
print_success("文件已添加到暂存区")
# 提交
print_info("提交变更...")
success, _, stderr = run_command(["git", "commit", "-m", commit_message])
if not success:
print_error("Git commit 失败")
if stderr:
print_error(stderr)
return False
print_success("变更已提交")
# 推送
print_info("推送到远程仓库...")
success, _, stderr = run_command(["git", "push", remote, branch])
if not success:
print_error("Git push 失败")
if stderr:
print_error(stderr)
return False
print_success("代码已推送到远程仓库")
return True
def step3_server_operations(server_user, server_host, server_path):
"""步骤3: 服务器操作"""
print_info("")
print_info("=" * 50)
print_info("步骤3: 服务器拉取代码并重启服务")
print_info("=" * 50)
if not server_user or not server_host:
print_info("未配置服务器信息，跳过服务器操作")
print_info("")
print_info("使用方法:")
print_info(" python deploy.py --server-user <用户> --server-host <地址>")
print_info("")
print_info("或手动执行:")
print_info(f" ssh user@host 'cd {server_path} && git pull origin master && docker-compose restart'")
return True
print_info(f"连接到服务器: {server_user}@{server_host}")
print_info(f"执行命令: cd {server_path} && git pull origin master && docker-compose restart")
remote_cmd = f"cd {server_path} && git pull origin master && docker-compose restart"
ssh_cmd = ["ssh", f"{server_user}@{server_host}", remote_cmd]
success, stdout, stderr = run_command(ssh_cmd)
if success:
print_success("服务器代码已更新，服务已重启")
if stdout:
print(stdout)
return True
else:
print_error("服务器操作失败")
if stderr:
print_error(stderr)
print_warning("提示: 请确保已配置SSH密钥，或手动执行服务器命令")
return False
def main():
parser = argparse.ArgumentParser(description="自动化部署脚本")
parser.add_argument(
"-m", "--message",
default="更新文档",
help="Git提交信息（默认: 更新文档）"
)
parser.add_argument(
"--server-user",
help="服务器用户名"
)
parser.add_argument(
"--server-host",
help="服务器地址"
)
parser.add_argument(
"--server-path",
default="~/devops/mkdocs",
help="服务器路径（默认: ~/devops/mkdocs）"
)
parser.add_argument(
"--skip-mkdocs",
action="store_true",
help="跳过mkdocs.yml更新"
)
parser.add_argument(
"--skip-git",
action="store_true",
help="跳过Git操作"
)
parser.add_argument(
"--skip-server",
action="store_true",
help="跳过服务器操作"
)
args = parser.parse_args()
# 加载配置
config = load_config()
server_config = config.get("server", {})
git_config = config.get("git", {})
# 使用配置或参数
server_user = args.server_user or server_config.get("user", "")
server_host = args.server_host or server_config.get("host", "")
server_path = args.server_path or server_config.get("path", "~/devops/mkdocs")
branch = git_config.get("branch", "master")
remote = git_config.get("remote", "origin")
try:
# 步骤1: 更新mkdocs.yml
if not args.skip_mkdocs:
if not step1_update_mkdocs():
sys.exit(1)
# 步骤2: Git操作
if not args.skip_git:
if not step2_git_operations(args.message, branch, remote):
sys.exit(1)
# 步骤3: 服务器操作
if not args.skip_server:
if not step3_server_operations(server_user, server_host, server_path):
sys.exit(1)
print_info("")
print_info("=" * 50)
print_success("部署完成！")
print_info("=" * 50)
except KeyboardInterrupt:
print_error("\n操作已取消")
sys.exit(1)
except Exception as e:
print_error(f"发生错误: {e}")
sys.exit(1)
if __name__ == "__main__":
main()

120
更新部署脚本/deploy.sh Normal file
View File

@@ -0,0 +1,120 @@
#!/bin/bash
# 自动化部署脚本
# 功能：更新mkdocs.yml -> Git提交推送 -> 服务器拉取并重启
# 配置参数
COMMIT_MESSAGE="${1:-更新文档}"
SERVER_USER="${2:-}"
SERVER_HOST="${3:-}"
SERVER_PATH="${4:-~/devops/mkdocs}"
# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
NC='\033[0m' # No Color
# 输出函数
info() {
echo -e "${CYAN}$1${NC}"
}
success() {
echo -e "${GREEN}✓ $1${NC}"
}
error() {
echo -e "${RED}✗ $1${NC}"
}
warning() {
echo -e "${YELLOW}⚠ $1${NC}"
}
# 错误处理
set -e
trap 'error "脚本执行失败，退出码: $?"' ERR
# 步骤1: 更新mkdocs.yml
info "========================================="
info "步骤1: 更新mkdocs.yml"
info "========================================="
if python3 ./add_docs_to_mkdocs.py; then
success "mkdocs.yml更新成功"
else
error "更新mkdocs.yml失败"
exit 1
fi
# 检查是否有变更
info ""
info "检查Git状态..."
if [ -z "$(git status --porcelain)" ]; then
info "没有文件变更，跳过Git操作"
exit 0
fi
info "发现以下变更:"
git status --short
# 步骤2: Git操作
info ""
info "========================================="
info "步骤2: Git提交和推送"
info "========================================="
# 添加所有变更
info "添加文件到Git..."
git add .
success "文件已添加到暂存区"
# 提交
info "提交变更..."
git commit -m "$COMMIT_MESSAGE"
success "变更已提交"
# 推送
info "推送到远程仓库..."
git push origin master
success "代码已推送到远程仓库"
# 步骤3: 服务器操作
if [ -n "$SERVER_USER" ] && [ -n "$SERVER_HOST" ]; then
info ""
info "========================================="
info "步骤3: 服务器拉取代码并重启服务"
info "========================================="
info "连接到服务器: ${SERVER_USER}@${SERVER_HOST}"
info "执行命令: cd $SERVER_PATH && git pull origin master && docker-compose restart"
if ssh "${SERVER_USER}@${SERVER_HOST}" "cd $SERVER_PATH && git pull origin master && docker-compose restart"; then
success "服务器代码已更新，服务已重启"
else
error "服务器操作失败"
warning "提示: 请确保已配置SSH密钥，或手动执行服务器命令"
exit 1
fi
else
info ""
info "========================================="
info "步骤3: 服务器操作（跳过）"
info "========================================="
info "未配置服务器信息，跳过服务器操作"
info ""
info "使用方法:"
info " ./deploy.sh [提交信息] [服务器用户] [服务器地址] [服务器路径]"
info ""
info "示例:"
info " ./deploy.sh '更新文档' user example.com ~/devops/mkdocs"
info ""
info "或手动执行:"
info " ssh user@host 'cd ~/devops/mkdocs && git pull origin master && docker-compose restart'"
fi
info ""
info "========================================="
success "部署完成！"
info "========================================="

14
更新部署脚本/deploy_config.json Normal file
View File

@@ -0,0 +1,14 @@
{
"server": {
"user": "your_username",
"host": "your_server.com",
"path": "~/devops/mkdocs"
},
"git": {
"branch": "master",
"remote": "origin"
},
"scripts": {
"update_mkdocs": "python .\\add_docs_to_mkdocs.py"
}
}

250
更新部署脚本/部署脚本使用说明.md Normal file
View File

@@ -0,0 +1,250 @@
# 部署脚本使用说明
## 概述
部署脚本将以下三个步骤合并为一个自动化流程：
1. 执行Python脚本更新mkdocs.yml
2. Git提交和推送代码
3. 服务器拉取代码并重启服务
## 脚本版本
提供了多个版本的脚本，适用于不同环境：
- **deploy.py**: Python版本（推荐，跨平台）
- **deploy.ps1**: PowerShell版本（Windows）
- **deploy.sh**: Bash版本（Linux/macOS）
- **deploy.bat**: 批处理版本（Windows）
## 快速开始
### 方法1: 使用Python脚本（推荐）
#### 基本使用
```bash
# 使用默认提交信息
python deploy.py
# 指定提交信息
python deploy.py -m "更新文档内容"
# 配置服务器信息
python deploy.py --server-user your_user --server-host your_server.com
```
#### 完整参数
```bash
python deploy.py \
-m "更新文档" \
--server-user your_user \
--server-host your_server.com \
--server-path ~/devops/mkdocs
```
#### 跳过某些步骤
```bash
# 只更新mkdocs.yml和Git，不操作服务器
python deploy.py --skip-server
# 只更新mkdocs.yml
python deploy.py --skip-git --skip-server
```
### 方法2: 使用配置文件
#### 1. 编辑配置文件
编辑 `deploy_config.json`:
```json
{
"server": {
"user": "your_username",
"host": "your_server.com",
"path": "~/devops/mkdocs"
},
"git": {
"branch": "master",
"remote": "origin"
}
}
```
#### 2. 运行脚本
```bash
# 使用配置文件中的设置
python deploy.py -m "更新文档"
```
### 方法3: Windows PowerShell
```powershell
# 基本使用
.\deploy.ps1
# 指定参数
.\deploy.ps1 -CommitMessage "更新文档" -ServerUser "user" -ServerHost "host.com"
```
### 方法4: Linux/macOS Bash
```bash
# 添加执行权限
chmod +x deploy.sh
# 基本使用
./deploy.sh
# 指定参数
./deploy.sh "更新文档" "user" "host.com" "~/devops/mkdocs"
```
### 方法5: Windows批处理
```cmd
# 基本使用
deploy.bat
# 指定参数
deploy.bat "更新文档" "user" "host.com" "~/devops/mkdocs"
```
## 配置说明
### 服务器配置
#### SSH密钥配置
确保已配置SSH密钥，避免每次输入密码：
```bash
# 生成SSH密钥（如果还没有）
ssh-keygen -t rsa -b 4096
# 复制公钥到服务器
ssh-copy-id user@server.com
```
#### 测试SSH连接
```bash
ssh user@server.com "echo 'SSH连接成功'"
```
### Git配置
确保Git已配置：
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```
## 使用示例
### 示例1: 完整部署流程
```bash
# 使用配置文件
python deploy.py -m "完善Obsidian笔记体系文档"
```
### 示例2: 只更新本地
```bash
# 跳过服务器操作
python deploy.py -m "本地更新" --skip-server
```
### 示例3: 只更新服务器
```bash
# 跳过mkdocs和Git操作
python deploy.py --skip-mkdocs --skip-git
```
## 错误处理
### 常见问题
#### 1. Python脚本执行失败
- 检查Python环境
- 检查add_docs_to_mkdocs.py是否存在
- 检查mkdocs.yml格式
#### 2. Git操作失败
- 检查Git配置
- 检查网络连接
- 检查远程仓库权限
#### 3. 服务器操作失败
- 检查SSH连接
- 检查服务器路径
- 检查Docker服务状态
### 调试模式
Python脚本会输出详细的执行信息，包括：
- 每个步骤的执行状态
- 错误信息和堆栈
- 命令执行结果
## 安全建议
### 1. 配置文件安全
- 不要将包含敏感信息的配置文件提交到Git
- 使用环境变量存储敏感信息
- 将deploy_config.json添加到.gitignore
### 2. SSH安全
- 使用SSH密钥而非密码
- 限制SSH访问权限
- 定期更新SSH密钥
### 3. 权限控制
- 限制服务器操作权限
- 使用最小权限原则
- 审计部署操作
## 高级用法
### 自定义脚本
可以修改脚本添加自定义逻辑：
```python
# 在deploy.py中添加自定义步骤
def custom_step():
print_info("执行自定义操作...")
# 自定义逻辑
pass
```
### 集成到CI/CD
可以将脚本集成到CI/CD流程中：
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [master]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Deploy
run: python deploy.py -m "CI自动部署"
```
## 相关文件
- `add_docs_to_mkdocs.py`: 更新mkdocs.yml的脚本
- `deploy_config.json`: 配置文件
- `docker-compose.yml`: Docker配置
## 注意事项
1. **备份重要数据**: 部署前建议备份
2. **测试环境**: 先在测试环境验证
3. **版本控制**: 确保代码已提交
4. **服务状态**: 确保服务器服务正常
## 相关链接
- [[部署说明]]
- [[使用说明]]