unihalle/maximapool

MaximaPool

Docker化版本的https://github.com/maths/stack_util_maximapool%E3%80%82

MaximaPool创建一个Maxima进程池，在大型生产环境中有诸多优势，包括可将Maxima进程部署在独立服务器上，以及通过池化避免STACK等待Maxima启动的时间（每次调用可节省超过250ms）。

本镜像中的STACK-maxima经过高度优化：使用池化前，一次Maxima shell调用约需4秒，现在仅需约100ms（含请求开销约200ms）。

• 代码托管于https://github.com/uni-halle/maximapool-docker%EF%BC%88https://github.com/uni-halle/maximapool-docker/issues%EF%BC%89
• 镜像发布于https://hub.docker.com/r/unihalle/maximapool
• 作者：Docker化由ITZ Uni Halle的应用系统部门完成；镜像包含多种开源软件，详情见Dockerfile。
• 支持：作为大学或研究机构，您可通过ITZ Helpdesk请求支持（可能需要一定时间）或直接联系作者；对于其他实体（包括企业），请访问作者主页获取联系方式和定价，可请求托管、支持或定制服务。报告问题和提交PR始终受欢迎并受赞赏。

未来规划

我们可能会迁移到更高效的https://github.com/mathinstitut/goemaxima%EF%BC%88%E7%94%B1GWDG%E5%BC%80%E5%8F%91%EF%BC%89%EF%BC%8C%E5%9B%A0%E5%85%B6%E4%BD%9C%E4%B8%BA%E5%A4%9A%E6%95%99%E8%82%B2%E6%9C%BA%E6%9E%84%E6%9C%8D%E5%8A%A1%E6%8F%90%E4%BE%9B%E5%95%86%EF%BC%8C%E8%83%BD%E9%80%9A%E8%BF%87%E5%9B%BA%E5%AE%9A%E5%91%98%E5%B7%A5%E6%8F%90%E4%BE%9B%E9%95%BF%E6%9C%9F%E6%94%AF%E6%8C%81%E3%80%82%E5%B1%8A%E6%97%B6%E6%9C%AC%E9%A1%B9%E7%9B%AE%E5%B0%86%E8%A2%AB%E5%BD%92%E6%A1%A3%EF%BC%8C%E4%B8%8D%E5%86%8D%E6%8E%A5%E6%94%B6%E6%9B%B4%E6%96%B0%E3%80%82

版本/标签选择

Docker Hub上提供多个版本/标签：https://hub.docker.com/r/unihalle/maximapool/tags/

确定所需版本

ILIAS（assStackQuestion插件）
运行命令：$(grep stackmaximaversion ${ILIAS_PLUGIN_STACK}/classes/stack/maxima/stackmaxima.mac | grep -oP "\d+")，其中${ILIAS_PLUGIN_STACK}是assStackQuestion插件目录的绝对或相对路径。

Moodle（moodle-qtype_stack插件）
运行命令：$(grep stackmaximaversion $MOODLE/question/type/stack/stack/maxima/stackmaxima.mac | grep -oP "\d+")，其中$MOODLE是服务器上Moodle站点的根目录。

注意事项

• 不要允许不受信任的用户直接访问本镜像创建的服务/容器，可通过HTTP（基础）认证反向代理请求，示例见下文。
• 若Docker使用**aufs**作为存储驱动，可能导致容器运行问题。可通过docker info查看当前存储驱动，对于Debian和Ubuntu（2018年后），推荐使用overlay2。

使用方法

创建以下文件：

volumes/pool.conf（请根据需求调整值，并确保文件对所有人可读[chmod o+r]）：

# Maxima池配置
# 时间单位：毫秒

# 大小限制
size.min = 5
size.max = 15

# 同时启动进程的限制，结合更新频率定义最大负载
start.limit = 4

# 池更新周期（更新间隔毫秒）
update.cycle = 500

# 用于估算的数据集大小，若使用量不恒定则不宜过大
adaptation.averages.length = 5

# 池大小取决于需求和启动时间，系统尝试维持最小大小，因需求可能变化，建议使用安全乘数
adaptation.safety.multiplier = 3.0

.env：

MAXIMAPOOL_ADMIN_PASSWORD=此处输入强密码！

仅使用Docker运行

docker run -d \
   --name TestMaximaPool \
   -e "MAXIMAPOOL_ADMIN_PASSWORD=此处输入强密码！" \
   -p "8765:8080" \
   -v "/path/to/volumes/pool.conf:/opt/maximapool/pool.conf:ro" \
   unihalle/maximapool

现在可访问池：[***]

使用docker-compose运行

最小示例（将8765端口绑定到localhost）：

docker-compose.yaml：

version: "2"
services:
  maximal-pool:
    image: unihalle/maximapool:stack-2017121800
    restart: always
    environment:
        - MAXIMAPOOL_ADMIN_PASSWORD
    ports:
        - "127.0.0.1:8765:8080"
    volumes:
        - "./volumes/pool.conf:/opt/maximapool/pool.conf:ro"

访问池：[***]
在docker-compose网络内，URL为http://maximal-pool:8080/MaximaPool/MaximaPool。

使用带HTTP基础认证和证书的代理

以下是完整示例，展示如何在docker-compose管理的网络中使用反向代理提供HTTP密码认证和加密。请将$VIRTUAL_HOST替换为实际主机名。

HTTP基础认证的缺点是每次请求都会哈希密码，若选择较重的哈希（>8）可能会减慢代理速度。

# 创建pool.conf和.env文件（如最小示例所述）

# 创建htpasswd文件（需安装apache-utils）
mkdir -p passwords && htpasswd -cBC 8 passwords/$VIRTUAL_HOST ${USER}
# 或使用Docker：docker run --rm httpd htpasswd -nbB ${USER} ${PASSWORD} > passwords/$VIRTUAL_HOST

# 添加证书供反向代理读取
mkdir -p certs && cp VIRTUAL_HOST.crt certs/ && cp VIRTUAL_HOST.key certs/

docker-compose.yaml：

version: "2"
services:
  maximal-pool:
    image: unihalle/maximapool:stack-2018030500
    restart: always
    environment:
        - MAXIMAPOOL_ADMIN_PASSWORD
        - VIRTUAL_HOST=$VIRTUAL_HOST
        - VIRTUAL_PORT=8080
    volumes:
        - "./volumes/pool.conf:/opt/maximapool/pool.conf:ro"
        - "./volumes/logs/tomcat:/usr/local/tomcat/logs"
        - "/etc/localtime:/etc/localtime:ro"
  reverse-proxy:
    image: jwilder/nginx-proxy:alpine
    environment:
        - DEFAULT_HOST=$VIRTUAL_HOST
    ports:
      - "8065:80"
      - "8765:443"
    restart: always
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./certs:/etc/nginx/certs:ro
      - ./passwords:/etc/nginx/htpasswd:ro

启动并查看日志：docker-compose up -d && docker-compose logs -f
配置正确的话，访问[***]
按Ctrl+C退出日志查看，Tomcat日志存储于./volumes/logs/tomcat。若需控制日志内容，可覆盖/usr/local/tomcat/conf/server.xml（https://tomcat.apache.org/tomcat-9.0-doc/config/valve.html#Access_Log_Valve%EF%BC%89%EF%BC%8C%E9%80%9A%E8%BF%87%E6%8C%82%E8%BD%BD%E6%96%87%E4%BB%B6%E6%88%96%E7%9B%AE%E5%BD%95%EF%BC%8C%E6%88%96%E4%BD%BF%E7%94%A8Dockerfile%E8%A6%86%E7%9B%96%E3%80%82

多版本/自定义STACK

可运行多个STACK版本或多个池：将包含正确内容和权限的卷挂载到/opt/maximapool/%%VERSION%%/。也可使用容器本身生成自定义STACK-maxima池，工具链、lisp和Maxima已预安装。

还可构建适用于特定版本Moodle https://github.com/maths/moodle-qtype_stack%E7%9A%84%E9%95%9C%E5%83%8F%EF%BC%9A%E7%A1%AE%E4%BF%9D%60assets/moodle-qtype_stack%60%E5%AD%90%E6%A8%A1%E5%9D%97%E8%B7%9F%E8%B8%AA%E4%B8%8EMoodle%E4%B8%AD%E5%AE%89%E8%A3%85%E7%9A%84%60qtype_stack%60%E6%8F%92%E4%BB%B6%E7%89%88%E6%9C%AC%E5%8C%B9%E9%85%8D%E7%9A%84%E6%8F%90%E4%BA%A4%EF%BC%8C%E7%84%B6%E5%90%8E%E4%BD%BF%E7%94%A8%60--build-arg BUILD_FOR_MOODLE=1`参数构建镜像。

与Moodle集成

在Moodle端，STACK配置位于“站点管理 -> 插件 -> 问题类型 -> STACK插件设置”。要与MaximaPool Docker容器配合使用，需设置：

• 平台类型：服务器
• Maxima版本：选择与所用镜像匹配的版本（如5.41.0）
• Maxima命令：maxima-pool:8080/MaximaPool/MaximaPool

maxima-pool是Maxima容器的主机名，需确保Moodle web服务器可访问。

贡献指南

• Dockerfile编写建议
• 发布新版本步骤：
  1. 发布到新分支
  2. 更新本README.md的兼容性矩阵
  3. 通过插件更新和重新配置生成新的/data_dir/xqcas/stack/maximalocal.mac
  4. 使用从/data_dir/xqcas/stack/maximalocal.mac（ILIAS）或$MOODLEDATA/stack/**/maximalocal.mac（Moodle）生成的值更新assets/maximalocal.mac.template和assets/optimize.mac

开发者指南：版本定位、跟踪与修改

定位stackmaxima

• Moodle https://github.com/maths/moodle-qtype_stack/blob/master/stack/maxima/stackmaxima.mac%EF%BC%9A%E6%9C%80%E5%90%8E%E4%B8%80%E8%A1%8C
• ILIAS https://github.com/ilifau/assStackQuestion/blob/master/classes/stack/maxima/stackmaxima.mac%EF%BC%9A%E6%9C%80%E5%90%8E%E4%B8%80%E8%A1%8C

修改stackmaxima

• Moodle：cd assets/moodle-qtype_stack && git checkout [ref] && cd ../.. && git add assets/moodle-qtype_stack && git commit -m "Update to STACK [stackversion]"（影响moodle-qtype_stack版本，可通过cd assets/moodle-qtype_stack && git log查看）
• ILIAS：cd assets/assStackQuestion && git checkout [ref] && cd ../.. && git add assets/assStackQuestion && git commit -m "Update to STACK [stackversion]"（影响assStackQuestion版本，可能影响ILIAS版本，assStackQuestion有master-ilias53等分支）

定位OS版本

• docker-compose exec [maximapool] bash -c 'cat /etc/debian_version'
• 在***查询
• 取决于Tomcat/JDK的基础镜像

定位与修改Tomcat/JDK版本

• 查看https://github.com/uni-halle/maximapool-docker/blob/develop/Dockerfile%E7%AC%AC%E4%B8%80%E8%A1%8C

定位与修改Maxima版本

• 查看https://github.com/uni-halle/maximapool-docker/blob/develop/Dockerfile%E5%B9%B6%E6%90%9C%E7%B4%A2%22Maxima-Linux"

需要监控变化的文件

• assets/optimize.mac：关注“此变量控制STACK支持的可选包”部分，确保加载所有相关包（参考Moodle https://github.com/maths/moodle-qtype_stack/blob/master/stack/cas/installhelper.class.php#L32%E3%80%81ILIAS https://github.com/ilifau/assStackQuestion/blob/629f817624b1dfb7cbb74aa0f1135c0ad39c56df/classes/stack/cas/installhelper.class.php#L37%EF%BC%8C%E6%88%96%E7%9B%B4%E6%8E%A5%E6%9F%A5%E7%9C%8BLMS%E7%94%9F%E6%88%90%E7%9A%84stackmaxima.mac%E6%96%87%E4%BB%B6%EF%BC%89
• assets/maximalocal.mac.template：参考Moodle https://github.com/maths/moodle-qtype_stack/blob/1130d860ebb8e03d78c6c7973ba48c2dfa844685/stack/maxima/sandbox.wxm%E3%80%81ILIAS https://github.com/ilifau/assStackQuestion/blob/629f817624b1dfb7cbb74aa0f1135c0ad39c56df/classes/stack/maxima/sandbox.wxm%EF%BC%8C%E4%BD%86%E5%BB%BA%E8%AE%AE%E7%9B%B4%E6%8E%A5%E6%9F%A5%E7%9C%8BLMS%E7%94%9F%E6%88%90%E7%9A%84stackmaxima.mac%E6%96%87%E4%BB%B6%E3%80%82

开发者指南：构建镜像

bash
git clone --recurse-submodules -j4 git@github.com:uni-halle/maximapool-docker.git # 若-j4导致问题可省略
cd maximapool-docker
docker build . # 或docker-compose build；可忽略未定义环境变量的警告

开发者指南：常见问题

• Q：build.xml不存在。
  A：请确保克隆时初始化子模块：git clone --recurse-submodules -j4 git@github.com:uni-halle/maximapool-docker.git；若已克隆，进入仓库目录并获取子模块：cd maximapool-docker && git submodule update --init --recursive