告别复杂配置！Wiki.js自定义域名与SSL证书实战指南

告别复杂配置！Wiki.js自定义域名与SSL证书实战指南

【免费下载链接】wiki- Wiki.js | A modern and powerful wiki app built on Node.js 项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-

在搭建Wiki.js知识库时，默认域名往往难以记忆且缺乏专业性。本文将带你通过三个步骤实现域名个性化与HTTPS加密，让你的Wiki站点既安全又专业。

配置前的准备工作

开始配置前，请确保你已完成以下准备：

• 拥有一个已备案的自定义域名（如wiki.yourdomain.com）
• 服务器已开放80/443端口
• 已安装Wiki.js并能通过默认地址访问
• 域名解析已指向服务器IP（A记录或AAAA记录）

第一步：基础域名设置

修改配置文件

Wiki.js的域名配置主要通过config.yml文件实现，该文件位于项目根目录。你需要修改以下关键参数：

# config.yml
host: 'wiki.yourdomain.com'
port: 3000
ssl:
  enabled: false
  redirectNonSSL: false
  domain: 'wiki.yourdomain.com'
  subscriberEmail: 'your-email@example.com'

修改完成后，重启Wiki.js服务使配置生效：

docker restart wikijs  # Docker部署方式
# 或
systemctl restart wikijs  # 系统服务方式

验证基础配置

访问http://服务器IP:3000，在Wiki.js管理界面的设置 > 一般中确认域名已更新：

Wiki.js一般设置

配置文件路径：config.sample.yml
管理界面组件：client/components/admin.vue

第二步：Let's Encrypt自动SSL配置

Wiki.js内置Let's Encrypt客户端，可自动申请和续期免费SSL证书。

启用自动SSL

修改config.yml文件中的SSL部分：

# config.yml
ssl:
  enabled: true
  redirectNonSSL: true
  provider: 'letsencrypt'
  domain: 'wiki.yourdomain.com'
  subscriberEmail: 'your-email@example.com'
letsencrypt:
  production: true
  agreeToTerms: true

工作原理简析

Wiki.js的SSL自动配置通过两个核心模块实现：

1. ACME挑战处理：server/controllers/ssl.js

   • 响应Let's Encrypt的HTTP-01验证请求
   • 位于/.well-known/acme-challenge/路径下的令牌验证

2. 证书管理逻辑：server/core/letsencrypt.js

   • 自动生成密钥对和证书签名请求(CSR)
   • 证书续期逻辑（默认提前5天更新）
   • 证书存储与服务器配置更新

第三步：手动SSL证书配置（高级用户）

对于需要使用自签名证书或商业证书的场景，可以手动配置SSL：

准备证书文件

将证书文件放置在服务器安全目录（如/etc/wiki-ssl/），需要以下文件：

• 私钥文件：privkey.pem
• 证书文件：fullchain.pem

修改配置文件

# config.yml
ssl:
  enabled: true
  redirectNonSSL: true
  provider: 'manual'
  keyPath: '/etc/wiki-ssl/privkey.pem'
  certPath: '/etc/wiki-ssl/fullchain.pem'
  passphrase: ''  # 如果私钥有密码

Nginx反向代理配置（可选）

对于生产环境，建议使用Nginx作为反向代理：

# /etc/nginx/sites-available/wiki.yourdomain.com
server {
    listen 80;
    server_name wiki.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name wiki.yourdomain.com;
    
    ssl_certificate /etc/wiki-ssl/fullchain.pem;
    ssl_certificate_key /etc/wiki-ssl/privkey.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

常见问题排查

证书申请失败

1. 端口占用问题：确保80端口未被其他服务占用
2. 域名解析问题：使用nslookup wiki.yourdomain.com验证解析
3. 防火墙设置：检查服务器防火墙和云服务商安全组
4. 日志查看：查看Wiki.js日志获取详细错误信息：

   tail -f /var/log/wikijs/error.log
   

重定向循环

当配置redirectNonSSL: true后出现重定向循环，通常是因为：

• 反向代理未正确传递X-Forwarded-Proto头
• 多层代理环境未配置trustProxy参数

解决方法：在config.yml中添加：

trustProxy: true

证书自动续期失败

Wiki.js会在证书到期前5天自动尝试续期。如失败，可手动触发：

node server/scheduler.js job:letsencrypt-renew

配置完成后的验证

1. 访问https://wiki.yourdomain.com，确认地址栏显示安全锁图标
2. 使用SSL检测工具（如SSL Labs评分）验证证书状态
3. 测试HTTP到HTTPS的自动跳转
4. 检查管理界面设置 > SSL中的证书信息：

Wiki.js SSL设置

总结

通过本文介绍的三个步骤，你已成功为Wiki.js配置了自定义域名和SSL证书：

1. 基础域名设置使Wiki.js识别自定义域名
2. Let's Encrypt自动配置实现免费SSL证书的申请与续期
3. 手动SSL配置满足高级用户的特殊需求

合理的域名与SSL配置不仅提升了站点专业性，也保障了数据传输安全。Wiki.js的证书自动续期功能可让你一劳永逸，无需担心证书过期问题。

完整配置示例：config.sample.yml
SSL核心代码：server/core/letsencrypt.js
管理界面：client/components/admin.vue

【免费下载链接】wiki- Wiki.js | A modern and powerful wiki app built on Node.js 项目地址: https://gitcode.com/GitHub_Trending/wiki78/wiki-