Synapse 部署：Python脚本映射路径长期方案
近期 Synapse 发布了 1.141.0 (2025-10-29) 版本，此版本的 Docker 镜像已基于 Debian trixie 和 Python 3.13。
🚨 问题所在
这次底层系统的更新，导致了 Python 软件包的安装路径发生了变化（从 python3.12 变为 python3.13）。
如果您之前使用我博客的中文搜索脚本，通过 docker-compose.yml 中的 volumes 来硬编码挂载自定义 Python 脚本，您的 Synapse 服务在更新后将无法启动。其他外挂的python模块同理，例如shared_secret_authenticator（网桥认证模块），
旧的、已失效的配置如下所示：
volumes:
- ./py_config/search.py:/usr/local/lib/python3.12/site-packages/synapse/storage/databases/main/search.py
- ./py_config/shared_secret_authenticator.py:/usr/local/lib/python3.12/site-packages/shared_secret_authenticator.py
您现在可以将其中映射路径中的python3.12改为python3.13即可正常启动。
✅ 推荐的长期解决方案
Synapse 的 python 环境会不定期的更变，为了更好解决这个问题，我引入了两种新的自动化方案。
1. 方案一 (针对 appservices 模块)
Appservices 模块是在 homeserver.yaml 中引入的新模块（如用于网桥的 shared_secret_authenticator），不需要替换 synapse 服务端已有的脚本，我们可以使用 PYTHONPATH 环境变量来动态添加一个自定义模块加载目录。
操作：
请在 docker-compose.yml 中，确保您有以下 environment 和 volumes 配置：
services:
synapse:
# ...
environment:
# ...
# 1. 添加此环境变量，让 Python 优先加载 /app/custom_py 目录
- PYTHONPATH=/app/custom_py
volumes:
# ...
# 2. 将您存放 .py 模块的本地目录挂载到 /app/custom_py
- ./py_config:/app/custom_py
原理： Python 会优先在 /app/custom_py 中寻找模块，而不用关心系统默认的 site-packages 路径如何变化。
2. 方案二 (针对 search.py 中文搜索支持)
对于需要覆盖 Synapse 默认文件的模块（如我们的中文搜索 search.py），我们使用一个自定义 entrypoint 脚本，在容器每次启动时自动检测正确的路径并覆盖文件。
操作：
请在 docker-compose.yml 中，修改/添加以下 volumes 和 entrypoint 配置：
services:
synapse:
# ...
volumes:
# ...
# 1. 挂载您的 search.py 补丁文件
- ./search.py:/config_patches/search.py:ro
# 2. 挂载新的 entrypoint 脚本 (下一步会创建它)
- ./entrypoint.sh:/custom_entrypoint.sh:ro
# 3. 覆盖默认的 entrypoint，指向我们的新脚本
entrypoint: /custom_entrypoint.sh
ACTION REQUIRED：如何更新
步骤 1：创建 entrypoint.sh 脚本
在您的 docker-compose.yml 同级目录下，创建一个名为 entrypoint.sh 的新文件，并将以下所有内容复制进去：
(注意：如果在Windows中创建的脚本，请将行尾序列改为适合 Linux shell 的 LF格式)
#!/bin/sh
# 确保脚本在出错时立即退出
set -e
# --- 这是我们注入的自定义逻辑 ---
echo "Custom Entrypoint: 正在检测 Python site-packages 路径..."
# 1. 在容器内部自动检测正确的 site-packages 路径
SITE_PACKAGES_PATH=$(python -c "import sysconfig; print(sysconfig.get_path('purelib'))")
if [ -z "$SITE_PACKAGES_PATH" ]; then
echo "Custom Entrypoint: 错误！无法检测到 site-packages 路径。"
exit 1
fi
# 2. 定义源文件和目标文件
SOURCE_FILE="/config_patches/search.py"
DEST_FILE="${SITE_PACKAGES_PATH}/synapse/storage/databases/main/search.py"
echo "Custom Entrypoint: 正在将补丁文件覆盖到: ${DEST_FILE}"
# 3. 执行覆盖操作
cp "${SOURCE_FILE}" "${DEST_FILE}"
echo "Custom Entrypoint: 覆盖完成。"
# --- 自定义逻辑结束 ---
# 4. 执行原始镜像的默认命令 (/start.py)
echo "Custom Entrypoint: 正在启动 Synapse 主程序 (/start.py)..."
exec /start.py "$@"
步骤 2：为脚本添加执行权限
在您的宿主机上运行：
chmod +x ./entrypoint.sh
步骤 3：更新您的 docker-compose.yml
确保您的 docker-compose.yml 文件已包含上面 方案一 和 方案二 中提到的所有 environment、volumes 和 entrypoint 更改。
步骤 4：拉取并重启服务
运行您常用的更新命令：
docker-compose pull && docker-compose up -d
您的服务现在应该会正常启动。entrypoint 脚本会自动处理 python3.13 (或未来任何版本) 的路径，一劳永逸。
补充说明
Synapse的默认 entrypoint 是 start.py，在我们的脚本中硬编码为最后执行，此默认入口名称可能也会更变（正常不会），请订阅我的博客（或Matrix频道）获得更新提醒。
评论