Showdoc开源版私有化部署踩坑全记录：从Docker搭建到内网穿透访问
Showdoc开源版私有化部署实战指南：从Docker到安全访问的全链路方案
在当今企业协作环境中，文档管理工具的安全性和可控性越来越受到重视。Showdoc作为一款优秀的开源文档工具，其SaaS版本虽然便捷，但无法满足企业对数据主权和隐私保护的严格要求。本文将带您完成一次完整的私有化部署之旅，涵盖从基础环境搭建到高级安全配置的全过程，特别针对企业内网环境下的特殊需求提供解决方案。
1. 环境准备与Docker部署
私有化部署Showdoc的第一步是选择合适的服务器环境。推荐使用Ubuntu 20.04 LTS或CentOS 7+作为基础操作系统，这些系统对Docker的支持最为成熟。在开始前，请确保服务器具备至少2核CPU、4GB内存和50GB存储空间，这对于中小型团队的文档管理已经足够。
1.1 安装Docker与Docker-Compose
现代应用部署离不开容器化技术，使用Docker可以大大简化Showdoc的安装和维护过程。以下是安装最新版Docker和Docker-Compose的完整命令集：
# 卸载旧版本（如有） sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io # 验证安装 sudo docker run hello-world # 安装Docker-Compose sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose注意：如果是在国内服务器部署，建议将Docker镜像源替换为国内镜像以加速下载，可以通过修改
/etc/docker/daemon.json文件实现。
1.2 部署Showdoc容器
Showdoc官方提供了完整的Docker镜像，我们可以通过docker-compose快速启动服务。创建一个docker-compose.yml文件，内容如下：
version: '3' services: showdoc: image: star7th/showdoc container_name: showdoc restart: always ports: - "4999:80" volumes: - ./showdoc_data/html:/var/www/html/ - ./showdoc_data/upload:/var/www/html/Public/Uploads environment: - TZ=Asia/Shanghai启动服务只需执行：
mkdir -p showdoc_data/{html,upload} docker-compose up -d部署完成后，通过http://服务器IP:4999即可访问Showdoc的安装界面。首次访问需要设置管理员账号和密码，建议使用强密码并妥善保管。
2. 生产环境配置优化
基础部署完成后，我们需要对Showdoc进行生产环境级别的配置优化，确保其稳定性和性能满足企业需求。
2.1 数据库性能调优
Showdoc默认使用SQLite作为数据库，这在小型团队中表现尚可，但对于文档数量较多或访问频繁的场景，建议迁移到MySQL。修改docker-compose.yml增加MySQL服务：
services: mysql: image: mysql:5.7 container_name: showdoc_mysql restart: always environment: MYSQL_ROOT_PASSWORD: your_strong_password MYSQL_DATABASE: showdoc MYSQL_USER: showdoc MYSQL_PASSWORD: showdoc_password volumes: - ./mysql_data:/var/lib/mysql command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --innodb_buffer_pool_size=1G showdoc: depends_on: - mysql environment: - DB_TYPE=mysql - DB_HOST=mysql - DB_NAME=showdoc - DB_USER=showdoc - DB_PASSWORD=showdoc_password迁移数据库后，还需要调整MySQL的配置参数以获得最佳性能：
[mysqld] innodb_buffer_pool_size = 1G innodb_log_file_size = 256M innodb_flush_log_at_trx_commit = 2 innodb_flush_method = O_DIRECT query_cache_type = 1 query_cache_size = 64M2.2 文件存储优化
Showdoc默认将上传的文件存储在本地，这在分布式部署时可能带来问题。我们可以将其配置为使用对象存储服务，如阿里云OSS或AWS S3。修改Showdoc的配置文件config/application.php：
'UPLOAD_TYPE' => 'oss', // 设置为oss或s3 'OSS_ACCESS_ID' => 'your_access_key', 'OSS_ACCESS_KEY' => 'your_secret_key', 'OSS_ENDPOINT' => 'oss-cn-hangzhou.aliyuncs.com', 'OSS_BUCKET' => 'your-bucket-name',对于图片等静态资源，建议启用CDN加速，可以显著提升用户访问体验。在Showdoc后台的"系统设置"中配置CDN域名即可。
3. 安全加固与访问控制
企业级部署必须考虑安全性问题，本节将介绍如何加固Showdoc部署，防止未授权访问和数据泄露。
3.1 HTTPS配置与Nginx反向代理
直接暴露Docker容器的HTTP端口存在安全风险，我们应该通过Nginx配置HTTPS反向代理。首先安装Nginx和Certbot获取SSL证书：
sudo apt-get install -y nginx certbot python3-certbot-nginx然后为Nginx创建配置文件/etc/nginx/sites-available/showdoc.conf：
server { listen 80; server_name docs.yourcompany.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name docs.yourcompany.com; ssl_certificate /etc/letsencrypt/live/docs.yourcompany.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/docs.yourcompany.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256...'; ssl_prefer_server_ciphers on; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; location / { proxy_pass http://localhost:4999; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 静态文件缓存 location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { proxy_pass http://localhost:4999; expires 30d; add_header Cache-Control "public, no-transform"; } # 限制上传文件大小 client_max_body_size 20M; }获取SSL证书并启用配置：
sudo certbot --nginx -d docs.yourcompany.com sudo ln -s /etc/nginx/sites-available/showdoc.conf /etc/nginx/sites-enabled/ sudo systemctl reload nginx3.2 访问控制与权限管理
Showdoc内置了基于项目的权限系统，但企业环境通常需要更细粒度的控制。我们可以通过以下方法增强访问控制：
- IP白名单限制：在Nginx配置中添加IP限制
allow 192.168.1.0/24; allow 10.0.0.0/8; deny all;- 双因素认证：通过修改Showdoc代码集成Google Authenticator
- 操作日志审计：定期备份
showdoc_data/html/Sqlite/showdoc.db中的操作日志 - 定期备份策略：设置自动备份脚本
#!/bin/bash BACKUP_DIR="/backups/showdoc" DATE=$(date +%Y%m%d) docker exec showdoc_mysql mysqldump -u root -p"your_strong_password" showdoc > $BACKUP_DIR/showdoc_db_$DATE.sql tar -czvf $BACKUP_DIR/showdoc_data_$DATE.tar.gz /path/to/showdoc_data find $BACKUP_DIR -type f -mtime +30 -delete4. 内网穿透与远程协作方案
企业内网部署的Showdoc需要让外部合作伙伴或远程团队安全访问，这需要内网穿透解决方案。以下是几种常见方案的对比：
| 方案 | 配置复杂度 | 安全性 | 稳定性 | 适用场景 |
|---|---|---|---|---|
| 传统VPN | 高 | 高 | 高 | 长期固定团队 |
| 反向代理 | 中 | 中 | 高 | 临时外部访问 |
| 商业内网穿透 | 低 | 中 | 中 | 快速验证场景 |
对于大多数中小企业，基于反向代理的方案在安全性和易用性之间取得了良好平衡。以下是配置示例：
# 在边缘Nginx服务器上配置 server { listen 443 ssl; server_name partner-access.yourcompany.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location /showdoc/ { proxy_pass http://internal-showdoc-server:4999/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 添加基本认证 auth_basic "Restricted Access"; auth_basic_user_file /etc/nginx/.htpasswd; # 限制访问时间段 if ($time_local ~ "^(Mon|Tue|Wed|Thu|Fri) (0[8-9]|1[0-7]):") { set $allow 1; } if ($allow != 1) { return 403; } } }创建基本认证密码文件：
sudo htpasswd -c /etc/nginx/.htpasswd partner_user对于需要更高安全性的场景，可以考虑基于客户端证书的认证：
ssl_client_certificate /path/to/ca.crt; ssl_verify_client on; location /showdoc/ { if ($ssl_client_verify != SUCCESS) { return 403; } proxy_pass http://internal-showdoc-server:4999/; }5. 高级功能定制与企业集成
私有化部署的优势在于可以根据企业需求进行深度定制。以下是几个常见的定制方向：
5.1 与企业SSO集成
将Showdoc与企业现有的LDAP或OAuth2认证系统集成，实现统一登录。这需要修改Showdoc的认证模块：
// 在application/common/Auth.php中添加自定义认证方法 public function ssoLogin($username, $password) { $ldapconn = ldap_connect("ldap://your-ldap-server"); ldap_set_option($ldapconn, LDAP_OPT_PROTOCOL_VERSION, 3); if ($ldapconn) { $ldapbind = ldap_bind($ldapconn, "cn=$username,ou=users,dc=yourcompany,dc=com", $password); if ($ldapbind) { // LDAP认证成功，查找或创建本地用户 $user = Db::name('user')->where('username', $username)->find(); if (!$user) { $data = [ 'username' => $username, 'password' => md5(random_str(8)), // 随机密码，实际使用LDAP认证 'groupid' => 2, // 普通用户 'reg_time' => time() ]; Db::name('user')->insert($data); } return true; } } return false; }5.2 自定义模板与工作流
企业可以根据自身文档规范创建定制模板。在web/Public/static/editor.md/lib目录下添加自定义模板：
// 在editor.js中添加模板 var myTemplates = { "API文档": "/**\n * showdoc\n * @catalog ${分类}\n * @title ${标题}\n... */", "技术方案": "## 背景\n\n## 方案设计\n\n## 实施计划" }; // 注册模板选择器 $('#template-selector').append( $.map(myTemplates, function(val, key) { return $('<option>').val(val).text(key); }) );5.3 自动化文档生成
与企业CI/CD流程集成，实现接口文档自动更新。创建一个自动化脚本：
#!/usr/bin/env python3 import requests import os API_KEY = "your_showdoc_api_key" API_TOKEN = "your_showdoc_api_token" SHOWDOC_URL = "https://docs.yourcompany.com/server/index.php?s=/api/open/fromComments" def generate_doc(project_id, file_path): with open(file_path, 'r') as f: content = f.read() response = requests.post(SHOWDOC_URL, data={ 'api_key': API_KEY, 'api_token': API_TOKEN, 'content': content }) if response.json().get('error_code') == 0: print(f"文档更新成功: {project_id}") else: print(f"文档更新失败: {response.text}") if __name__ == "__main__": for root, _, files in os.walk("src"): for file in files: if file.endswith(".js"): generate_doc("frontend", os.path.join(root, file))