WikiDocs 部署与使用完全笔记

一、容器文件复制操作

基本复制命令

将容器 wikidoc 中 /var/lib/wikidocs/datasets/documents 目录下所有文件复制到宿主机 /data/wikidoc：

podman cp wikidoc:/var/lib/wikidocs/datasets/documents/. /data/wikidoc/

关键注意事项

源路径末尾的 /. 表示复制目录下的所有内容而非目录本身。目标路径末尾的 / 表示将内容放入目标目录内部。

如果目标文件夹不存在，可去掉末尾斜杠，Podman 会自动创建目录但会多一层目录结构：

podman cp wikidoc:/var/lib/wikidocs/datasets/documents /data/wikidoc

容器不需要处于运行状态，Exited 状态也可执行复制操作。

保留文件权限

使用 -a 参数可完全保留文件属主和权限包括 UID/GID 映射：

podman cp -a wikidoc:/var/lib/wikidocs/datasets/documents/. /data/wikidoc/

二、权限问题与解决方案

问题现象

容器日志报错：DATASETS directory </var/lib/wikidocs/datasets> is not writable

根本原因

容器内应用以 PUID=1000 和 PGID=1000 的用户运行，但宿主机挂载目录的所有者不是 UID 1000，导致容器内用户无写入权限。

解决方案

方案一：修改宿主机目录权限（推荐）

podman-compose down
sudo chown -R 1000:1000 /data/wikidoc/datasets
podman-compose up -d

如仍无效可尝试更宽松的权限：

sudo chmod -R 777 /data/wikidoc/datasets

方案二：容器以 root 用户运行（不推荐，有安全风险）

在 docker-compose.yml 中添加：

services:
  wikidocs:
    user: root

权限验证命令

查看目录权限：

ls -la /data/wikidoc/datasets

确认容器内用户 ID：

podman exec wikidoc id

查看容器日志：

podman logs -f wikidoc

三、Docker Compose 配置详解

基础配置文件

volumes:
  datasets:

services:
  wikidocs:
    image: zavy86/wikidocs:2
    environment:
      MODE: public|private
      SECRET: generate-a-secret-key-here
    volumes:
      - datasets:/var/lib/wikidocs/datasets
    ports:
      - "3210:3210"

环境变量说明

SECRET 变量

这是必需的安全设置，用于加密会话和防止 CSRF 攻击。

重要：必须将 generate-a-secret-key-here 替换为随机生成的复杂字符串，不可保留示例文字。

生成随机字符串的命令：

openssl rand -base64 32

MODE 变量

控制 Wiki 访问权限，需从 public 或 private 中选择一个：

MODE: public - 公开模式，任何人可查看无需登录。适合对外分享的技术文档或产品手册。

MODE: private - 私有模式，访问需登录认证。适合个人笔记或团队内部知识库。

注意：配置文件中 MODE: public|private 的写法是错误的，必须二选一。

完整推荐配置

services:
  wikidocs:
    image: zavy86/wikidocs:2
    environment:
      MODE: private
      SECRET: 使用openssl rand -base64 32生成的随机字符串
    volumes:
      - /data/wikidoc/datasets:/var/lib/wikidocs/datasets
    ports:
      - "3210:3210"
    restart: unless-stopped

四、文件管理与访问

支持的文件类型

核心内容文件

Markdown 文件（.md）是 Wiki 页面的基础存储格式，所有页面均以纯文本 Markdown 文件保存。

Markdown 扩展支持包括：

KaTeX 数学公式渲染
Mermaid 图表（流程图、时序图等）
语法高亮
YAML Frontmatter

富媒体与附件

图片支持上传，可从剪贴板直接粘贴截图。

其他附件支持任何文件类型，作为页面附件提供下载。

注意：WikiDocs 无法像浏览器那样直接预览 PDF、Word 等非网页格式文档，这些文件以附件链接形式提供下载。

文件放置方式

使用 Docker 卷时需先查看卷的实际位置：

podman volume inspect datasets

推荐使用宿主机目录挂载，方便管理：

volumes:
  - /data/wikidoc/datasets:/var/lib/wikidocs/datasets

网页访问方法

访问地址：http://服务器IP:3210

访问限制说明：

必须通过 WikiDocs Web 界面访问
无法通过直接访问 .md 文件链接的方式浏览
所有访问需经过 WikiDocs 前端路由

命名注意事项：

页面路径会自动将大写字母转为小写
手动输入路径时需使用小写字母
首页文件需放在 datasets 目录根目录下

五、文件组织结构

目录结构

WikiDocs 使用文件夹对内容进行分类（命名空间），文件目录结构直接反映在 Wiki 页面导航中。

页面索引

系统可自动生成索引和站点地图，方便内容浏览和查找。

组织建议

使用有意义的文件夹名称进行分类
首页文件放置在根目录
相关页面放在同一子文件夹中
文件名使用小写字母和连字符，避免空格和特殊字符

六、常用运维命令

容器管理

# 查看配置
podman-compose config

# 后台启动
podman-compose up -d

# 停止容器
podman-compose down

# 查看日志
podman logs -f wikidoc

# 查看容器状态
podman ps -a

权限管理

# 递归修改目录所有者
sudo chown -R 1000:1000 /data/wikidoc/datasets

# 查看目录权限详情
ls -la /data/wikidoc/datasets

七、故障排查要点

常见问题及解决思路：

目录不可写：检查宿主机目录所有者是否为 UID 1000
文件无法访问：确认文件是否放置在正确的挂载位置
页面无法显示：检查文件命名是否符合规范（小写字母）
容器无法启动：检查 SECRET 是否已设置且不为示例值

WikiDocs部署与使用笔记