> ## Content Index
> Fetch the complete content index at: https://nigzu.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Synapse 部署：Python脚本映射路径长期方案
- URL: https://nigzu.com/synapse-selfhosted-update-python-path-change-solution/
- Published: 2025-11-03T05:23:08.000Z
- Updated: 2025-11-03T05:26:39.000Z
- Author: 宁嘉
- Tags: Matrix, 自托管

近期 Synapse [发布了](https://github.com/element-hq/synapse/releases?ref=nigzu.com) `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`（网桥认证模块），

**旧的、已失效的配置**如下所示：

```yaml
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 配置：

```yaml
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 配置：

```yaml
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格式)

```bash
#!/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：为脚本添加执行权限**

在您的宿主机上运行：

```bash
chmod +x ./entrypoint.sh

```

**步骤 3：更新您的 `docker-compose.yml`**

确保您的 `docker-compose.yml` 文件已包含上面 **方案一** 和 **方案二** 中提到的所有 `environment`、`volumes` 和 `entrypoint` 更改。

**步骤 4：拉取并重启服务**

运行您常用的更新命令：

```Bash
docker-compose pull && docker-compose up -d

```

您的服务现在应该会正常启动。`entrypoint` 脚本会自动处理 `python3.13` (或未来任何版本) 的路径，一劳永逸。

##### 补充说明

Synapse的默认 entrypoint 是 `start.py`，在我们的脚本中硬编码为最后执行，此默认入口名称可能也会更变（正常不会），请订阅我的博客（或[Matrix频道](https://matrix.to/?ref=nigzu.com#/#feed:nigzu.com)）获得更新提醒。