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 [archamd64 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: - TZAsia/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-serverutf8mb4 --collation-serverutf8mb4_unicode_ci --innodb_buffer_pool_size1G showdoc: depends_on: - mysql environment: - DB_TYPEmysql - DB_HOSTmysql - DB_NAMEshowdoc - DB_USERshowdoc - DB_PASSWORDshowdoc_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.phpUPLOAD_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.confserver { 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 -pyour_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,ouusers,dcyourcompany,dccom, $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))
Showdoc开源版私有化部署踩坑全记录:从Docker搭建到内网穿透访问
发布时间:2026/6/9 4:48:13
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 [archamd64 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: - TZAsia/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-serverutf8mb4 --collation-serverutf8mb4_unicode_ci --innodb_buffer_pool_size1G showdoc: depends_on: - mysql environment: - DB_TYPEmysql - DB_HOSTmysql - DB_NAMEshowdoc - DB_USERshowdoc - DB_PASSWORDshowdoc_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.phpUPLOAD_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.confserver { 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 -pyour_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,ouusers,dcyourcompany,dccom, $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))