常见问题
GEO Wiki Pro 知识库平台常见问题解答，帮助快速解决部署、配置和使用中的问题
> 快速解决您在使用 GEO Wiki Pro 时遇到的问题
---
## 🔧 安装部署
### Q: 如何安装 GEO Wiki Pro？
**A:** 有两种安装方式：
**方式一：Docker 部署（推荐）**
```bash
# 克隆代码
git clone https://github.com/your-org/geo-wiki-pro.git
cd geo-wiki-pro
# 配置环境变量
cp .env.example .env
# 编辑 .env，设置 JWT_SECRET（至少 32 位）
# 启动服务
docker-compose up -d
# 验证
curl http://localhost:3002/api/v1/health
```
**方式二：本地开发**
```bash
# 安装依赖
npm install
# 启动前后端
npm run dev:full
```
### Q: 宝塔面板如何部署？
**A:** 请参考 [宝塔部署指南](/docs/baota-deployment)，包含完整的 Nginx 配置和常见问题解决方案。
### Q: Docker 部署后无法访问？
**A:** 请检查以下几点：
1. **端口是否映射**：确保 `docker-compose.yml` 中端口映射正确
2. **.env 配置**：确认 `JWT_SECRET` 已设置且长度 >= 32
3. **查看日志**：`docker compose logs api` 检查错误信息
4. **防火墙**：确保端口未被防火墙阻拦
---
## 🌐 多语言
### Q: 如何添加新语言？
**A:** 按以下步骤操作：
1. 创建翻译文件 `src/i18n/{lang}.json`
2. 在 `src/utils/i18n.js` 中注册新语言
3. 在 `data/docs/{lang}/` 目录下创建文档
4. 使用 CLI 创建：`geo doc create --file doc.md --lang {lang}`
### Q: 不同语言的文档如何同步？
**A:** GEO Wiki Pro 使用级联合并机制：
- 中文 (zh) 是基础语言
- 查询其他语言时，先读取中文文档作为基础，再用目标语言覆盖
- `category`、`tags`、`author`、`sort` 是共享字段，会自动同步到所有语言版本
- `title`、`description`、`content` 是独立字段，每个语言可以不同
---
## 📝 文档管理
### Q: 如何通过 CLI 管理文档？
**A:** 使用 `geo` 命令行工具：
```bash
# 安装
npm install -g geowiki-cli
# 登录
geo login --url https://geowiki.pro
# 创建文档
geo doc create --file article.md --category support --sort 1
# 更新文档
geo doc update --slug my-doc --file updated.md --lang zh
# 删除文档
geo doc delete --slug old-doc
# 查看文档列表
geo doc list --category support
```
### Q: slug 是什么？如何选择？
**A:** slug 是文档的 URL 标识符，用于生成访问链接。规则：
- 只能包含字母、数字、连字符、下划线
- 最大长度 200 字符
- 建议使用英文小写和连字符
- 示例：`docker-deployment`、`faq`、`rest-api`
### Q: 如何调整文档排序？
**A:** 在管理后台的文档列表页面，支持拖拽排序。也可以通过 API：
```bash
curl -X PUT "https://geowiki.pro/api/v1/admin/docs/reorder" \
-H "Content-Type: application/json" \
-b "jwt=your-token" \
-d '{"slugs": ["doc-1", "doc-2", "doc-3"], "category": "support", "lang": "zh"}'
```
---
## 🎨 Markdown 扩展
### Q: 支持哪些扩展语法？
**A:** GEO Wiki Pro 支持以下扩展语法：
| 语法 | 说明 | 示例 |
|------|------|------|
| `:::video[说明](url)` | 视频嵌入 | `:::video[演示视频](https://bilibili.com/...)` |
| `:::model[标题](url)` | 3D 模型卡片 | `:::model[产品模型](/media/model.step)` |
| `::: note` / `::: tip` / `::: warning` | 提示框 | 信息提示、技巧、警告 |
| `::: faq` | FAQ 块 | 问答对格式 |
| `` | 图片（alt 自动显示为图注） | `` |
| `[名称](url)` | 文件下载卡片 | `[用户手册](/media/manual.pdf)` |
---
## 🔒 安全问题
### Q: 如何保护管理后台？
**A:** GEO Wiki Pro 提供多层安全保护：
1. **JWT 认证**：httpOnly cookie，2 小时自动过期
2. **CSRF 保护**：Double-submit cookie HMAC 验证
3. **CSP 策略**：Helmet nonce-based Content Security Policy
4. **限流**：全局 300 次/分钟，认证接口 10 次/分钟
5. **密码加密**：bcrypt 加密存储
6. **首次登录强制改密**
### Q: 如何设置 HTTPS？
**A:** 推荐使用 Nginx 反向代理 + Let's Encrypt：
```nginx
server {
listen 443 ssl http2;
server_name geowiki.pro;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:3002;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
---
## 📡 API 相关
### Q: API 如何认证？
**A:** 使用 JWT cookie 认证：
```bash
# 登录获取 token
curl -X POST "https://geowiki.pro/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "your-password"}' \
-c cookies.txt
# 使用 token 访问管理接口
curl "https://geowiki.pro/api/v1/admin/docs" \
-b cookies.txt
```
### Q: 公开接口需要认证吗？
**A:** 不需要。以下接口完全公开：
- `GET /api/v1/docs` — 文档列表
- `GET /api/v1/docs/:slug` — 单篇文档
- `GET /api/v1/docs/search` — 搜索
- `GET /api/v1/categories` — 分类
- `GET /api/v1/tags` — 标签
- `GET /api/v1/config` — 站点配置
- `GET /api/v1/llms.txt` — AI 爬虫 Feed
- `GET /api/v1/geo/sitemap.xml` — 站点地图
---
## 📚 更多资源
- [快速入门](/docs/cli-quick-reference)
- [Docker 部署](/docs/docker-deployment)
- [REST API 文档](/docs/rest-api)
- [Markdown 扩展语法](/docs/markdown-extensions)
---
*最后更新: 2026-06-06 | 版本: v3.0.2*