Wiki 部署教程

一、部署前准备

1.1 环境要求

1.2 安装 MySQL

以 CentOS / Ubuntu 通用方式为例（如已安装可跳过）：

# 创建数据目录（可选）
mkdir -p /data/mysql

# 启动 MySQL 容器方式（示例）
docker run -d --name mysql \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=your_password \
  -v /data/mysql:/var/lib/mysql \
  mysql:5.7

1.3 创建数据库

登录 MySQL 后执行：

CREATE DATABASE IF NOT EXISTS mm_wiki DEFAULT CHARSET utf8;

二、方式一：Linux 二进制部署（推荐）

2.1 下载并解压

前往项目仓库的 Releases 发布页面，下载对应平台的压缩包（例如 mm-wiki-linux-amd64.tar.gz），上传到服务器后执行：

mkdir -p /opt/mm_wiki
cd /opt/mm_wiki

# 解压（文件名按实际下载的版本调整）
tar -zxvf mm-wiki-linux-amd64.tar.gz

ls -l

解压后目录结构大致如下：

mm_wiki/
├── install/            # 安装向导程序
├── conf/               # 配置文件目录
├── static/             # 静态资源
├── views/              # 模板文件
├── logs/               # 日志目录
├── mm-wiki             # 主程序
└── run.sh              # 启动脚本（部分版本提供）

2.2 运行安装向导

cd /opt/mm_wiki/install
chmod +x install
# 默认监听 8090 端口，如需修改：
# ./install --port=8087
./install

安装程序启动后，浏览器访问 http://服务器IP:8090，按向导填写：

• 数据库地址、端口、用户名、密码、数据库名（mm_wiki）
• 站点名称、站点地址
• 管理员账号（用户名、密码、邮箱）
• 数据存储目录（默认程序目录下的 data）

提交后向导会自动建表并写入配置，页面提示安装成功即可。

注意：安装完成后务必按 Ctrl + C 停止 install 程序，否则主程序无法启动。

2.3 启动 MM-Wiki

cd /opt/mm_wiki
./mm-wiki --conf conf/mm-wiki.conf

浏览器访问 http://服务器IP:8090，使用安装时设置的管理员账号登录（默认示例为 admin / mmwiki）。

2.4 使用脚本后台运行（推荐）

若压缩包内自带 run.sh，可用脚本管理进程：

chmod +x run.sh mm-wiki
./run.sh start      # 启动
./run.sh status     # 查看状态
./run.sh stop       # 停止
./run.sh restart    # 重启

日志位于 logs/mm-wiki.log，PID 文件位于 logs/mm-wiki.pid。

2.5 配置 systemd 开机自启

创建服务文件 /etc/systemd/system/mm-wiki.service：

[Unit]
Description=MM-Wiki Service
After=network.target mysqld.service

[Service]
Type=simple
WorkingDirectory=/opt/mm_wiki
ExecStart=/opt/mm_wiki/mm-wiki --conf /opt/mm_wiki/conf/mm-wiki.conf
Restart=on-failure
RestartSec=5
StandardOutput=append:/opt/mm_wiki/logs/mm-wiki.log
StandardError=append:/opt/mm_wiki/logs/mm-wiki.log

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable mm-wiki
systemctl start mm-wiki
systemctl status mm-wiki

三、方式二：Windows 部署

3.1 解压与安装

1. 下载 mm-wiki-windows-amd64 平台压缩包，手动解压到例如 D:\mm_wiki。
2. 确认本机已安装 MySQL，并创建 mm_wiki 数据库。
3. 进入 install 目录，双击 install.exe。

3.2 完成安装向导

浏览器访问 http://服务器IP:8090，按向导填写数据库与管理员信息，完成安装。

安装完成后关闭 install 窗口（非常重要，否则端口被占用）。

3.3 启动主程序

打开命令行（cmd）进入程序根目录：

cd /d D:\mm_wiki
mm-wiki.exe --conf conf\mm-wiki.conf

浏览器访问 http://服务器IP:8090 即可使用。

3.4 注册为 Windows 服务（可选）

可使用 NSSM 等工具把 mm-wiki.exe 注册为服务，实现开机自启：

nssm install MM-Wiki "D:\mm_wiki\mm-wiki.exe" "--conf conf\mm-wiki.conf"
nssm set MM-Wiki AppDirectory "D:\mm_wiki"
nssm start MM-Wiki

四、方式三：Docker 部署

4.1 准备数据库表

Docker 方式不会运行安装向导，需要手动导入表结构：

# 进入项目源码的 docs/databases 目录，或在容器内找到该目录
cd mm-wiki/docs/databases

# 导入表结构
mysql -h127.0.0.1 -uroot -p mm_wiki < table.sql

# 导入初始数据
mysql -h127.0.0.1 -uroot -p mm_wiki < data.sql

注意：data.sql 中第一条管理员用户插入语句默认是注释状态，需要手动取消注释后再导入，否则没有管理员账号。默认管理员为 admin / mmwiki，请登录后立即修改密码。

4.2 准备配置文件

在宿主机创建目录并放置配置文件：

mkdir -p /data/mm-wiki/conf /data/mm-wiki/data

将项目中的配置文件复制为 /data/mm-wiki/conf/mm-wiki.conf，并修改数据库连接与数据存放目录。典型内容如下（字段名以实际版本为准）：

[server]
http_addr = 0.0.0.0
http_port = 8081

[db]
host = 127.0.0.1
port = 3306
username = root
password = your_password
dbname = mm_wiki

[log]
level = 5

[install]
data_path = /data/mm-wiki/data

若使用 Docker，数据库地址不要写 127.0.0.1，应写宿主机在容器网络中可访问的 IP（或在同一网络下使用 MySQL 容器名）。

4.3 使用 DockerHub 镜像启动（推荐）

docker run -d \
  --name mm-wiki \
  -p 8080:8081 \
  -v /data/mm-wiki/conf/:/opt/mm-wiki/conf/ \
  -v /data/mm-wiki/data/:/data/mm-wiki/data/ \
  eahom/mm-wiki:v0.1.7

启动后访问 http://服务器IP:8080。

4.4 本地构建镜像启动

git clone <项目仓库地址> mm-wiki   # 例如 phachon/mm-wiki 项目的主仓库
cd mm-wiki

docker build -t mm-wiki-image .

docker run -d \
  --name mm-wiki \
  -p 8080:8081 \
  -v /data/mm-wiki/conf/:/opt/mm-wiki/conf/ \
  -v /data/mm-wiki/data/:/data/mm-wiki/data/ \
  mm-wiki-image

容器内默认启动命令为：

/opt/mm-wiki/mm-wiki --conf /opt/mm-wiki/conf/mm-wiki.conf

4.5 docker compose 示例（可选）

version: "3"
services:
  mysql:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: your_password
      MYSQL_DATABASE: mm_wiki
    volumes:
      - ./mysql:/var/lib/mysql
    restart: always

  mm-wiki:
    image: eahom/mm-wiki:v0.1.7
    ports:
      - "8080:8081"
    volumes:
      - ./conf/:/opt/mm-wiki/conf/
      - ./data/:/data/mm-wiki/data/
    depends_on:
      - mysql
    restart: always

注意：使用 compose 时，配置文件中的数据库地址应写 mysql（服务名）。

五、Nginx 反向代理配置

生产环境建议用 Nginx 代理并托管静态资源：

upstream mmwiki_frontends {
    server 127.0.0.1:8090;   # MM-Wiki 实际监听的 ip:port
}

server {
    listen 80;
    server_name wiki.example.com;

    location / {
        proxy_pass_header Server;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme $scheme;
        proxy_pass http://mmwiki_frontends;
        client_max_body_size 100m;   # 附件上传大小限制
    }

    # 静态资源交给 nginx 处理
    location /static {
        root /opt/mm_wiki;
        expires 1d;
        add_header Cache-Control public;
        access_log off;
    }
}

配置 HTTPS 时，建议同时设置：

proxy_set_header X-Forwarded-Proto $scheme;

并在后端配置中使用 https 站点地址，避免跳转异常。

检查并重载：

nginx -t && nginx -s reload

六、安装后的基本配置

1. 登录后台管理，进入「系统设置」：
   • 填写站点名称、站点地址、Logo
   • 配置数据存储目录、附件上传大小
2. 进入「角色管理」，按需创建角色并授予权限（如文档管理、空间管理、系统设置等）。
3. 进入「用户管理」，创建部门与用户，并分配角色。
4. 进入「空间管理」，创建空间（对应部门/团队），设置访问级别（private / public）、是否允许分享与导出，并添加成员及空间权限（浏览者 / 编辑者 / 管理员）。
5. 按需配置「邮件设置」，开启文档变更通知。
6. 如需对接公司 LDAP 等外部认证，在「登录认证」中新增认证接口，填写名称、用户名前缀、认证 URL 及额外参数。

七、常见问题

7.1 访问页面提示无法连接数据库

• 检查 MySQL 是否启动、端口是否开放；
• 检查配置文件中的数据库地址、用户名、密码、库名是否正确；
• Docker 部署时不要使用 127.0.0.1 作为数据库地址。

7.2 安装完成后访问 8090 无响应

• 确认 install 程序已按 Ctrl + C 停止；
• 确认主程序已用 --conf 指向正确的配置文件；
• 查看 logs/mm-wiki.log 是否有报错。

7.3 忘记管理员密码

可直接在数据库中更新用户表密码字段为已知 MD5 值（mw_user 表 password 字段存的是 32 位 MD5），或修改用户 role_id、is_forbidden 状态后重新登录。

7.4 附件上传失败或过小

• 检查 Nginx 的 client_max_body_size；
• 检查后台系统设置中的上传大小限制与数据目录写权限。

7.5 静态资源 404、页面样式错乱

• 检查 Nginx location /static 的 root 是否指向 MM-Wiki 根目录；
• 确认 static 目录已随程序一起部署。

7.6 端口被占用

启动时修改端口（安装阶段）：

./install --port=8087

运行阶段则修改配置文件中的监听端口，并同步调整 Nginx 上游地址。

7.7 数据备份

• 数据库：定期 mysqldump 导出 mm_wiki 库；
• 附件与数据目录：备份配置中的数据目录（如 /data/mm-wiki/data）；
• 配置文件：备份 conf/mm-wiki.conf。

示例备份脚本：

#!/bin/bash
DATE=$(date +%F)
mysqldump -uroot -pyour_password mm_wiki > /backup/mm_wiki_${DATE}.sql
tar -czf /backup/mm_wiki_data_${DATE}.tar.gz /data/mm-wiki/data

八、升级方法

1. 备份数据库与数据目录；
2. 停止服务：

systemctl stop mm-wiki
# 或 ./run.sh stop

3. 下载新版本压缩包，解压后覆盖程序文件（保留 conf/、data/、logs/ 目录）；
4. 如新版本包含数据库变更，按发布说明执行相应 SQL；
5. 启动服务并验证访问。

systemctl start mm-wiki

九、部署检查清单

• [ ] MySQL 已安装并创建 mm_wiki 数据库（utf8 字符集）
• [ ] 程序文件与 conf/static/views/logs 目录完整
• [ ] 安装向导已完成并停止 install 程序
• [ ] 主程序可正常启动，日志无报错
• [ ] 已配置 systemd / 服务守护，实现开机自启
• [ ] Nginx 反向代理与静态资源配置正确
• [ ] 管理员密码已修改，角色与用户已初始化
• [ ] 数据备份脚本已配置并验证