1. 部署前哨先把Sakai 20.0的老底摸清楚先聊点实在的。Sakai这个名字国内很多高校老师和做在线教育的同行应该不陌生它是一个开源的在线协作与学习平台说白了就是一套帮学校、培训机构搭网络教学环境的系统。20.0这个版本核心变化之一是把底层架构往新方向推了推不再强行依赖老旧的那套运行环境对部署者来说最直接的好处是依赖关系更清爽、组件升级的余地更大。很多刚接触Sakai的人容易有个误解以为它是个像WordPress那样装上就能用的现成站点。实际上它更接近一套需要自己组装的服务底层用Java技术栈数据存数据库文件走存储系统前面还要挂一层代理做请求分发。部署Sakai 20.0本质上是在服务器上把这些上下游组件按正确姿势拼起来。我这次部署用的是常规的Linux服务器环境以CentOS系为例数据库选用MySQL 5.7以上版本JDK要求是1.8或1120.0对JDK 11的支持已经比较成熟了。如果你手头是Ubuntu/Debian系命令上做对应替换即可核心逻辑完全一致。整个部署过程如果一切顺利、网络带宽也正常大约需要两个小时左右但如果你跟我一样中途踩了版本兼容的坑预留半天比较稳妥。这个部署方案适合谁参考一类是想在内部服务器上自建在线教学平台的学校IT老师另一类是想基于Sakai做二次开发的研发同学还有一类就是单纯被领导安排“把Sakai跑起来”的运维朋友。不管你是哪一类这篇梳理都会尽量把部署链路讲透让它从“能跑”变成“跑得稳”。2. 部署架构拆解Sakai 20.0凭什么这样搭2.1 先搞懂Sakai 20.0运行时的“三驾马车”Sakai 20.0的部署不是单进程操作它运行时依托三条核心链路我习惯叫它“三驾马车”。第一驾是应用服务器Sakai本身是一个Java Web应用打包成WAR文件放在应用服务器里跑20.0版本官方默认支持Apache Tomcat 9这个版本选型很关键因为Tomcat 9对应Servlet 4.0规范能跟Sakai 20.0的新组件兼容第二驾是数据库Sakai的所有课程、用户、权限、作业、论坛帖子都存在关系型数据库里官方推荐MySQL20.0开始对MySQL 8.0的原生支持也变好了第三驾是文件存储课程上传的附件、用户头像这类二进制文件不会进数据库而是落到服务器磁盘或对象存储Sakai 20.0默认走本地文件系统路径通常在/usr/local/sakai/files或者你自定义的目录。三条链路的关系可以类比成一个餐厅应用服务器是前台服务员接收顾客浏览器用户的点单数据库是后厨的账本记录每桌客人点了什么文件存储则是冷藏库放着那些不用写进账本但必须保鲜的食材。三者缺一不可任何一个环节没对齐Sakai就会出现奇奇怪怪的问题——最常见的就是“页面能开但头像加载失败”或者“附件传不上来”多半是文件存储权限或路径配置出了岔子。2.2 为什么推荐用源码包而不是发行版自带的包管理工具安装有些朋友图省事直接用系统自带的yum install sakai之类的命令装结果往往会遇到版本过旧、依赖冲突、配置文件分散的问题。Sakai 20.0我强烈建议从官方发布的二进制包或源码包走原因有三点。首先Sakai官方对版本的发布节奏不是跟着Linux发行版走的你用系统的包管理器装到的很可能还是老版本功能差异大且已知漏洞多其次用源码包你能看到完整的目录结构和配置文件出问题时知道去哪里排查第三Sakai部署随意性很强不同学校有不同的域名、端口、数据库前缀包管理器装完你还得手动改一堆地方跟直接解压源码包再改配置没本质区别反倒多了一层包管理器的干扰。个人经验是下载sakai-20.0的二进制分发包一般是.tar.gz格式解压到/usr/local/sakai目录下然后以/usr/local/sakai作为CATALINA_HOME来运行。这样后续所有配置、日志、应用包都集中在一个根目录下排查问题的时候非常省心。2.3 服务器配置的底线要求Sakai 20.0对服务器配置的要求不算夸张但也没法寒酸。根据我自己的压测经验如果是给一个几百人规模的高校做内部教学平台最低配建议2核CPU 4GB内存 40GB SSD磁盘如果是上千人同时在线的高峰场景4核CPU 8GB内存会更从容磁盘根据附件量做弹性扩展。这里要特别提醒一句Sakai 20.0启动时JVM堆内存的默认配置往往偏保守在/usr/local/sakai/bin/setenv.sh或catalina.sh里务必把JAVA_OPTS的-Xms和-Xmx调大我自己的生产环境设置的是-Xms2048m -Xmx4096m。如果不调高并发时你会频繁看到OutOfMemoryError这个坑我踩过不止一次。3. 数据库与基础环境准备细到每一步的实操3.1 JDK 11安装与验证Sakai 20.0在JDK版本上官方给的选项是JDK 1.8或JDK 11。JDK 8目前虽然还在支撑很多老项目但Sakai 20.0的某些新特性在JDK 11下表现更稳我用的是OpenJDK 11。安装没有什么花哨的# CentOS / RHEL 系 sudo yum install -y java-11-openjdk-devel # Ubuntu / Debian 系 sudo apt-get install -y openjdk-11-jdk装完务必验证一下版本java -version如果显示的是openjdk version 11.0.x这类信息说明Java环境已就绪。这里有个细节容易忽略安装完OpenJDK后系统里可能还残留着旧版本的Java用alternatives --config java把默认Java版本切到11否则后面启动Tomcat时会莫名报UnsupportedClassVersionError那大概率就是JDK版本不对。3.2 MySQL 5.7的安装与字符集陷阱Sakai 20.0的数据库我用的是MySQL 5.7这也是官方文档里测试比较充分的组合。安装方式照旧# CentOS 7 sudo yum install -y https://dev.mysql.com/get/mysql57-community-release-el7-11.noarch.rpm sudo yum install -y mysql-community-server # Ubuntu 18.04 sudo apt-get install -y mysql-server启动服务并设为开机自启sudo systemctl enable mysqld sudo systemctl start mysqldMySQL 5.7首次启动会生成一个临时root密码在/var/log/mysqld.log里可以找到。用临时密码登录后第一件事就是改密码并创建一个Sakai专用账号ALTER USER rootlocalhost IDENTIFIED BY YourStrongPassword; CREATE DATABASE sakai CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; CREATE USER sakailocalhost IDENTIFIED BY SakaiDBPassword; GRANT ALL PRIVILEGES ON sakai.* TO sakailocalhost; FLUSH PRIVILEGES;字符集这里必须展开说。Sakai 20.0默认建表时会使用utf8mb4字符集如果数据库实例的默认字符集不是utf8mb4后面导入SQL脚本时可能出现乱码、索引过长甚至直接报错。所以你在my.cnf里最好显式加上[mysqld] character-set-serverutf8mb4 collation-serverutf8mb4_binutf8mb4_bin这个排序规则是二进制比较适合Sakai内部对代码表、资源标识这类字段的精确匹配需求。我曾经因为偷懒用了默认的utf8mb4_general_ci虽然大部分功能正常但Sakai的权限模块在某些场景下会出现“明明赋了权限却不生效”的怪问题后来改成utf8mb4_bin重建库就解决了。3.3 上传Sakai 20.0安装包并解压到Sakai官网的下载页面找Sakai 20.0对应的二进制包一般文件名类似sakai-20.0-2021-xx-xx.tar.gz。放到服务器后解压到目标目录sudo mkdir -p /usr/local/sakai sudo tar -xzf sakai-20.0-2021-xx-xx.tar.gz -C /usr/local/sakai --strip-components1注意这一步要充分理解--strip-components1的作用解压出来的第一层目录名通常带版本号类似sakai-20.0如果不剥离这一层你的CATALINA_HOME就变成了/usr/local/sakai/sakai-20.0后续所有配置路径都要多套一层非常麻烦。4. 核心配置文件逐项解析这些参数缺一不可4.1sakai.properties的必改项Sakai 20.0的核心配置集中在/usr/local/sakai/sakai/sakai.properties这个文件里。与其说是“配置文件”不如说它是Sakai全部运行时行为的“总开关”。从头到尾过一遍最关键的几项缺一不可。首先确定你的站点地址server.namelearn.youruniversity.edu.cn server.port8080 server.urlhttp://learn.youruniversity.edu.cn:8080这三个参数决定了Sakai生成页面链接时使用的域名和端口。如果你后面用Nginx做反向代理对外提供443端口服务这里的server.url要写成对外域名否则用户在浏览器里看到的部分链接会指向内网端口直接打不开。然后是数据库连接配置usernamesakaiorg.sakaiproject.db.usersakai passwordsakaiorg.sakaiproject.db.passwordSakaiDBPassword urlsakaiorg.sakaiproject.db.vendormysql urlsakaiorg.sakaiproject.db.drivercom.mysql.jdbc.Driver urlsakaiorg.sakaiproject.db.urljdbc:mysql://localhost:3306/sakai?useUnicodetruecharacterEncodingutf8mb4useSSLfalseallowPublicKeyRetrievaltrueurlsakaiorg.sakaiproject.db.url这项特别关键我加上了useUnicodetruecharacterEncodingutf8mb4useSSLfalseallowPublicKeyRetrievaltrue这些参数其中allowPublicKeyRetrievaltrue是为了应对MySQL 8.0以上版本在使用caching_sha2_password认证时可能出现的连接报错但你现在用的是MySQL 5.7useSSLfalse可以免去证书配置的麻烦characterEncodingutf8mb4则确保数据库读写不乱码。文件存储路径也不可忽视sakai.home/usr/local/sakai/sakai privatePathsakaiorg.sakaiproject.content.types.../usr/local/sakai/filesprivatePath是Content Hosting的根目录如果你用NFS或对象存储做共享这里就填挂载路径。4.2server.xml的关键调优Tomcat的server.xml在/usr/local/sakai/conf目录下。需要改的地方不多但必改的是端口和编码Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 URIEncodingUTF-8 /URIEncodingUTF-8这一项建议手动加上否则URL里带中文文件名时会出现乱码Sakai的附件下载功能直接受影响。还有一处容易被忽视默认的maxThreads200在生产环境偏低建议调整为400左右根据服务器CPU核数动态调8核以内建议不超过400。4.3 日志配置排错时最依赖的朋友Sakai日志默认输出到/usr/local/sakai/logs/目录。sakai.log和catalina.out是最常看的两个文件前者记录Sakai业务逻辑的日志后者是Tomcat运行日志。如果启动时卡住不报错先看catalina.out如果某个功能报500去翻sakai.log。我习惯启动后用这个命令实时盯日志tail -f /usr/local/sakai/logs/catalina.out结合grep按时间点过滤关键错误排查效率高很多。5. 数据库初始化与Sakai启动从空白到第一个页面5.1 导入Sakai的初始SQL脚本Sakai 20.0的安装包里自带数据库初始化脚本一般放在/usr/local/sakai/docs/sql/mysql/目录下。这个脚本会创建一组初始表结构和默认数据比如管理员账号、默认站点类型导入前先把Sakai服务停掉避免抢资源或表锁冲突cd /usr/local/sakai/docs/sql/mysql mysql -u sakai -pYourStrongPassword sakai sakai_20.0.sql导入过程根据服务器性能不同可能耗时几分钟到十几分钟耐心等待不要中途打断。导入完成后可以用mysql -u sakai -pYourStrongPassword -e USE sakai; SHOW TABLES;验证一下看到类似SAKAI_USER、SAKAI_SITE、SAKAI_REALM这些表都建出来了说明数据库初始化成功。这里有件特别容易踩坑的事如果你的MySQL版本是8.0导入时可能会因为旧版SQL脚本里的TYPEMyISAM之类语法而报错需要先做语法修正。Sakai 20.0的官方脚本对MySQL 5.7和8.0都做了适配但如果你用的第三方整理的脚本还是留个心眼。5.2 设置JVM内存与启动参数启动Sakai前务必把内存参数调到位。编辑/usr/local/sakai/bin/setenv.shJAVA_OPTS-Xms2048m -Xmx4096m -Djava.awt.headlesstrue-Djava.awt.headlesstrue这个参数在生成验证码图片、图表时会用到不加在某些环境里会报HeadlessException。-Xms和-Xmx要结合服务器物理内存调整我的机器是8GB物理内存-Xms2048m保证启动时快速分配好堆内存-Xmx4096m给Sakai足够的高峰期缓冲。5.3 首次启动与初始化执行启动命令cd /usr/local/sakai/bin ./startup.sh第一次启动因为有大量初始化工作建索引、缓存预热可能会慢一些一两分钟没输出完全正常。看日志确认启动成功的标志是类似这样的行INFO: Server startup in [xxxxx] milliseconds出现Server startup且没有ERROR就可以打开浏览器访问http://你的服务器IP:8080了。第一次访问会看到Sakai的默认首页用系统默认管理员账号一般是admin初始密码在导入SQL脚本中定义了通常是admin但强烈建议登录后立刻修改登录。6. Nginx反向代理与HTTPS让Sakai真正对外可用6.1 为什么必须要加一层反向代理Sakai 20.0的Tomcat默认裸露在8080端口直接用IP和端口访问虽然能通但存在三个问题一是浏览器会提示不安全没有HTTPS二是学校网络环境下防火墙通常只放行80和443端口8080在外部不可达三是Tomcat对大量静态资源的并发处理能力不如Nginx。所以外层加一个Nginx反向代理是生产部署的标准姿势。6.2 Nginx配置实战安装Nginx之后在/etc/nginx/conf.d/sakai.conf里新增如下配置server { listen 80; server_name learn.youruniversity.edu.cn; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name learn.youruniversity.edu.cn; ssl_certificate /etc/nginx/ssl/your_cert.pem; ssl_certificate_key /etc/nginx/ssl/your_cert.key; client_max_body_size 1000m; location / { proxy_pass http://127.0.0.1:8080; 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; proxy_connect_timeout 60s; proxy_read_timeout 300s; proxy_send_timeout 300s; } }client_max_body_size这条要特别留意。Sakai里学生上传大附件是常态默认Nginx只允许1MB左右的上传体积不调大这个参数用户一传稍大点的文件就会收到413错误。我这里设置成1000m实际根据你服务器的存储和带宽调整。proxy_read_timeout设成300秒是为了防止长时间请求比如导入课程备份被Nginx提前掐断。Sakai里某些管理操作耗时较长默认60秒的代理超时会造成前端“操作中心”的任务在后台执行完成后页面却报504的假失败排查起来非常迷惑。配置完成后记得nginx -t systemctl reload nginx同时在sakai.properties里把server.url改成HTTPS开头的对外域名避免页面上出现混合内容提示。7. 部署中高频踩坑与排查方法直接照单抓药7.1 “页面转圈半天最后报500”的排查套路Sakai部署完成打开首页最常遇到的就是白屏转圈然后500。你先分清是“前端无法到达服务”还是“后端抛异常”。方法很简单直接访问http://IP:8080绕过Nginx看能不能出页面。如果直接访问也不通就是Tomcat没起来或端口被占用如果直连能通但经Nginx不通问题在Nginx配置。Tomcat端口占用有一个独家排查技巧lsof -i:8080如果有大量TIME_WAIT连接占着端口稍微等一下或者重启Tomcat都能解决如果是LISTEN状态但不是java进程那就说明有别的服务抢占了8080直接改掉server.xml端口更省心。7.2 数据库连接失败一篇分清是驱动、账号还是网络问题数据库连接失败是Sakai部署里出现频率最高的报错之一日志里常见的几种提示要会区分。第一种Access denied for user sakailocalhost——这是账号权限或密码不对重新用mysql -u sakai -pYourStrongPassword -e USE sakai; SELECT 1;验证一遍即可。第二种Could not create connection to database server——这种通常是MySQL服务没启动systemctl status mysqld看一眼就知道。第三种Unknown database sakai——这是初始化脚本没导入返回5.1节把SQL脚本跑一遍。第四种值得单独提Public Key Retrieval is not allowed。这个报错在MySQL 8.0及以上版本常见因为默认用了caching_sha2_password认证。解决方案就是在JDBC URL里加allowPublicKeyRetrievaltrueuseSSLfalse5.7一般遇不到但如果你后面升级数据库版本这个经验直接用得上。7.3 文件上传/下载异常的定位思路Sakai里附件功能出问题大部分是privatePath指向的目录没有写权限。用ps aux | grep tomcat查看当前进程的运行用户然后用chown -R sakaiUser:sakaiUser /usr/local/sakai/files把目录属主改对顺便确认目录磁盘空间。另外Nginx层如果报413那是client_max_body_size不够大如果报504多半是proxy_read_timeout太短。这些错误在Nginx的error.log里都会有记录看日志比猜快得多。7.4 启动卡在“Deploying web application archive”的终极耐心方案Tomcat第一次启动Sakai时因为要解压并部署整个WAR包体积通常在几百MB日志会长时间停在Deploying web application archive sakai-tomcat...这一行。很多朋友这时候以为卡死了其实只是慢。我的建议是不要反复startup.sh和shutdown.sh来回折腾否则极易把部署锁搞坏出现“undeploy失败”的异常。判断是否真卡死看CPU用top看java进程的CPU占用率如果是持续高CPU说明还在解压部署耐心等如果CPU完全闲着日志也不动那可能是锁了关掉进程后删除/usr/local/sakai/work/Catalina/localhost下的缓存目录再重启。8. 安全加固与日常维护经验8.1 修掉默认密码和管理后台的暴露Sakai 20.0部署完第一件要紧事就是改掉默认管理员密码。默认admin账号的初始密码在官方文档里都有不换等于把大门敞开。另外Sakai的管理员操作入口和普通用户登录页面虽然走同一套路径但强烈建议对/admin这类管理路径做额外的Nginx访问控制比如限定只能从校园网内网IP访问外人一律403。8.2 数据库定时备份方案Sakai里存量数据就是学校的教学资产一旦丢了非常麻烦。我建议用系统定时任务每天做一次逻辑备份mysqldump -u sakai -pYourStrongPassword sakai --default-character-setutf8mb4 /backup/sakai_$(date %Y%m%d).sql配合日志轮转保留最近7天的备份文件即可。恢复的话也很直接mysql -u sakai -pYourStrongPassword sakai /backup/sakai_20250204.sql8.3 升级路线与版本兼容提醒目前Sakai 20.0之后已经迭代出更高的版本如果后续要升级务必先读对应版本的升级说明。多数情况需要先停服务、备份数据库、替换安装包再执行增量升级脚本。唯一要提醒的是——别跨大版本直接跳比如从20.0一步跨到很新的版本其中间可能有数据结构变动一次性跨越大概率出问题按官方给的路径一步步走才稳。9. 部署完成后的自测清单这几件事没做等于白装部署不能以页面能打开作为成功标准。我习惯按下面这份清单逐项过一遍全部通过才算收工。首先是用户登录链路。用管理员账号登录后台再创建测试账号走一遍完整登录流程确认权限分配、首页布局没问题。其次是核心功能链路。创建一门测试课程加入测试学生账号上传一份附件再以学生视角下载附件同时发一篇论坛帖子、提交一次作业看整条学习路径是否顺畅。第三是多媒体与文件上传。传一个稍大点的文件比如20MB以上的视频或压缩包确认Nginx和Tomcat两层都没有超时或413错误。第四是重启自恢复。执行一次/usr/local/sakai/bin/shutdown.sh然后startup.sh确认服务能正常拉起数据库连接、文件目录权限这些都自动就位。这一步能提前暴露很多“开机自启服务没配好”的坑。最后是访问日志抽查。打开/usr/local/sakai/logs/sakai.log看有没有周期性刷出的异常堆栈。很多问题不是部署时爆发而是运行一两天才出现提前把日志看住后面能少熬夜。10. 写在最后的小经验Sakai 20.0的部署本质上是一个“把Java应用、数据库、文件系统、反向代理四样东西理顺”的过程。我在实际部署中最大的体会是Sakai的部署难点不在某个单点而在组件之间的协作细节——字符集、内存参数、路径权限、代理超时任何一环出了偏差都会让你在用户端看到一个莫名其妙的问题。如果你也是第一次部署Sakai我的建议是先在一台测试机上完整走通一遍把每一步的日志、参数、报错都记录清楚再上生产。不要试图跳过数据库初始化直接启动不要省掉Nginx那一层更不要用默认密码上线。按照前面这些步骤一步步来Sakai 20.0是可以做到“装好即稳”的。后面如果遇到具体的报错欢迎在评论区把日志贴出来我也很乐意一起分析。