mkdocs/更新部署脚本/部署脚本使用说明.md

# 部署脚本使用说明

## 概述

部署脚本将以下三个步骤合并为一个自动化流程：
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. **服务状态**: 确保服务器服务正常

## 相关链接

- [[部署说明]]
- [[使用说明]]