发布指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 发布, 上线, 生产发布, 版本发布, 更新
---

# 一键发布脚本使用指南

## 功能说明

`publish-all.sh` 脚本可以一键完成以下任务：

1. ✅ 更新项目知识库内的所有相关文档和更新日志
2. ✅ 更新首页知识库所有的相关文档和更新日志
3. ✅ 代码推送到仓库
4. ✅ 相关更新的文档重新推送到仓库的WIKI（标题全部用中文）
5. ✅ 推送完检查，是否成功，比如仓库WIKI中是否推送了英文标题的文档，有就改成中文或删除

## 使用方法

### 方式1：使用 pnpm 命令（推荐）

```bash
pnpm publish
```

### 方式2：直接执行脚本

```bash
./scripts/publish-all.sh
```

## 执行流程

脚本会按以下顺序执行：

1. **检查Git仓库** - 确认当前目录在Git仓库中
2. **更新知识库文档** - 调用知识库导入API更新文档
3. **提交代码更改** - 检测并提交代码更改
4. **推送到仓库** - 将代码推送到远程仓库
5. **检查英文标题** - 扫描所有Markdown文件，检查是否有英文标题
6. **重新发布** - 如果修改了标题，重新提交并推送

## 注意事项

### 1. 服务必须运行

在执行脚本前，请确保开发服务正在运行：

```bash
pnpm dev
```

脚本需要调用知识库导入API：`http://localhost:5000/api/knowledge/import`

### 2. 英文标题检测

脚本会自动检测所有Markdown文件的第一行（标题），如果发现可能是英文标题（以英文字母开头），会提示：

```
[WARN] 发现可能的英文标题: ./docs/xxx.md - English Title
是否修改为中文标题？(y/n):
```

- 输入 `y`：修改为中文标题
- 输入 `n`：跳过修改

### 3. 提交信息

脚本会提示输入提交信息：

```
请输入提交信息（默认: update: 更新知识库和文档）:
```

直接按回车使用默认信息，或输入自定义提交信息。

## 示例

```bash
# 执行发布
pnpm publish

# 输出示例：
# [INFO] ======================================
# [INFO]    开始一键发布流程
# [INFO] ======================================
#
# [INFO] ✓ Git仓库检查通过
# [INFO] 步骤1: 开始更新知识库文档...
# [INFO] ✓ 知识库文档更新成功
# [INFO] 步骤2: 检查代码更改...
# [INFO] 发现更改，准备提交...
# 请输入提交信息（默认: update: 更新知识库和文档）:
# [INFO] ✓ 代码提交成功
# [INFO] 步骤3: 推送代码到仓库...
# [INFO] ✓ 代码推送成功
# [INFO] 步骤4: 检查文档标题...
# [INFO] 步骤5: 没有需要重新提交的更改
#
# [INFO] ======================================
# [INFO]    ✓ 所有步骤完成
# [INFO] ======================================
```

## 故障排除

### 问题1：知识库API调用失败

**错误信息**：
```
[WARN] 知识库API调用失败，请确保服务正在运行
```

**解决方法**：
1. 确保开发服务正在运行：`pnpm dev`
2. 检查服务是否在5000端口：`curl -I http://localhost:5000`

### 问题2：Git推送失败

**错误信息**：
```
[ERROR] 代码推送失败
```

**解决方法**：
1. 检查远程仓库配置：`git remote -v`
2. 检查网络连接
3. 检查是否有权限推送

### 问题3：文件权限错误

**错误信息**：
```
bash: ./scripts/publish-all.sh: Permission denied
```

**解决方法**：
```bash
chmod +x scripts/publish-all.sh
```

## 自定义配置

如果需要自定义脚本行为，可以编辑 `scripts/publish-all.sh` 文件：

- 修改默认提交信息
- 调整英文标题检测逻辑
- 添加额外的检查步骤

## 快捷别名

如果经常使用此脚本，可以在 `~/.bashrc` 或 `~/.zshrc` 中添加别名：

```bash
alias pub='cd /workspace/projects && pnpm publish'
```

这样就可以在任何位置使用 `pub` 命令快速发布了。