不灭的焱

Wiki.js 与私有 Gitea 仓库同步，核心是配置 Git 存储模块，推荐 SSH 部署密钥（稳定安全）或 HTTPS + 访问令牌（简易），实现双向自动同步。

一、准备 Gitea 仓库

1. 新建仓库（建议私有）
2. 初始化（至少有 main / master 分支）
3. 记录地址：
   • SSH：git@gitea.your-domain.com:user/wiki-repo.git
   • HTTPS：https://gitea.your-domain.com/user/wiki-repo.git

二、方式 A：SSH 密钥（推荐）

1. 生成密钥（无密码）

# 生成 ed25519 密钥（推荐）
ssh-keygen -t ed25519 -C "wikijs-gitea" -f wikijs-gitea
# 密码直接回车（留空）

得到：

• wikijs-gitea（私钥）
• wikijs-gitea.pub（公钥）

2. Gitea 添加部署密钥

• 进入仓库 → Settings → Deploy Keys
• Title：wikijs
• Key：粘贴 wikijs-gitea.pub 全文
• ✅ Allow write access（必须）
• Add Key
  

3. Wiki.js 配置（Admin → Storage → Git）

• Active：✅ 启用
• Friendly Name：Gitea Wiki
• Repository URI：SSH 地址
• Branch：main
• Authentication Type：SSH
• SSH Private Key Mode：Contents
• SSH Private Key Contents：粘贴 wikijs-gitea 全文
• Default Author：姓名 / 邮箱
• Sync Direction：Bi-directional
• Sync Interval：300 秒
• Local Repository Path：默认
  

三、方式 B：HTTPS + 访问令牌（简易）

1. Gitea 生成令牌

• 右上角头像 → Settings → Applications
• Generate New Token
  • Name：wikijs
  • Scopes：repo（完整仓库权限）
• Generate Token → 复制保存（只显示一次）
  

2. Wiki.js 配置

• Authentication Type：Basic (HTTPS)
• Username：Gitea 用户名
• Password / Token：粘贴生成的令牌
• 其余同 SSH 配置

四、启动同步

1. 右上角 Apply
2. 底部操作：
   • Add Untracked Changes：加入现有页面
   • Force Sync：立即同步
3. 状态：绿色 ✅ 成功；红色 ❌ 看日志（Admin → Logs） 

五、同步机制

• Wiki → Gitea
  • 页面增删改 → 自动 commit + push
  • 按路径生成 .md（带 YAML 头）
• Gitea → Wiki
  • 定时拉取 → 自动更新页面
  • Git 直接写 .md → Force Sync → 导入

六、常见问题

1. SSH 权限错误
   • 部署密钥未开 Write access
   • 私钥格式错误（保留换行）
2. HTTPS 403
   • 令牌权限不足（需 repo）
3. 不同步
   • 检查 Sync Interval
   • 手动 Force Sync
4. Docker
   • 映射 ./data/repo
   • 确保容器网络可访问 Gitea

七、最佳实践

• 优先 SSH 部署密钥
• 仓库设为 私有
• 开启 Wiki.js 版本历史 + Git 双重备份
• .gitignore 建议：

  node_modules/
  tmp/
  *.log
  

 

 

Wiki 是使用 docker-compose 安装的，如何映射 ./data/repo ？

你用 docker-compose 安装的 Wiki.js，只需要修改 docker-compose.yml，添加一行目录挂载，就能把容器内的 Git 同步目录 ./data/repo 映射到宿主机本地，实现持久化 + 正常同步 Gitea。

一、先找到你的 docker-compose.yml

默认 Wiki.js 官方 compose 文件长这样：

version: "3"
services:
  wikijs:
    image: ghcr.io/requarks/wiki:2
    container_name: wikijs
    depends_on:
      - db
    environment:
      - DB_TYPE=postgres
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=wikijs
      - DB_PASS=wikijs
      - DB_NAME=wikijs
    restart: unless-stopped
    ports:
      - "80:3000"
    # 👇 在这里添加 volumes 挂载
    volumes:
      - ./data/repo:/wiki/data/repo  # 👈 关键配置

  db:
    image: postgres:15-alpine
    container_name: wikijs-db
    environment:
      - POSTGRES_DB=wikijs
      - POSTGRES_USER=wikijs
      - POSTGRES_PASSWORD=wikijs
    restart: unless-stopped
    volumes:
      - ./db:/var/lib/postgresql/data

二、只需要加这一行（最重要）

在 wikijs 服务下，添加 volumes 挂载：

volumes:
  - ./data/repo:/wiki/data/repo

解释

• 左边 ./data/repo = 你宿主机当前目录下的文件夹（自动创建）
• 右边 /wiki/data/repo = Wiki.js 容器内默认的 Git 同步目录

三、重启容器生效 

# 停止
docker-compose down

# 重新启动（后台运行）
docker-compose up -d

启动后，宿主机就会自动生成：

你的目录/
├─ docker-compose.yml
├─ data/
│  └─ repo/        # 👈 Git 仓库同步文件都在这里
└─ db/

四、权限问题（必看！否则同步失败）

Docker 容器内默认用 uid 1000 运行，宿主机目录可能权限不足。

快速修复权限（最稳）

sudo chown -R 1000:1000 ./data/repo

或者直接给最大权限（测试环境用）：

chmod -R 777 ./data/repo

五、验证是否映射成功

# 进入容器
docker-compose exec wikijs sh

# 查看目录
ls -la /wiki/data/repo

能看到文件 = 映射成功 ✅

六、回到 Wiki.js 后台配置 Gitea

现在你可以正常配置：

• Admin → Storage → Git
• Local Repository Path = 默认 /wiki/data/repo 不用改
• 直接用 SSH / HTTPS 连接 Gitea
• 点 Force Sync 就会同步到宿主机 ./data/repo

总结

1. 在 docker-compose.yml 加一行：./data/repo:/wiki/data/repo
2. 执行 docker-compose up -d
3. 修复目录权限 chown -R 1000:1000 ./data/repo
4. Git 同步正常工作