Installing.zh_CN

🌐 English · Deutsch · Español · Français

安装（gramps-connect-desktop）

gramps-connect-desktop 是 Gramps Connect 的独立版本：一个可下载的应用，把 app/ 前端和 gramps-web-api 后端连同 SQLite 打包在一起，完全在您自己的电脑上运行。它是如今试用 Gramps Connect 最简单的方式，也是在自己的家谱上进行日常工作时 Gramps 桌面版的真正替代品——而不是其他什么东西的受限预览版。

它在设计上就是单用户的：它只监听 127.0.0.1，因此它的任何部分都无法通过网络访问，并且始终只有一个硬编码的登录账号 admin / admin。如果您希望全家人登录同一棵共享家谱，或者想亲眼看到实时协作功能，请改看部署——独立版看不到别人的编辑出现。

当前所有下载都在**最新发布版**中。它们都从一棵空家谱开始——运行后，通过应用自己的 家谱 → 导入... 界面导入您自己的 Gramps XML（.gramps）或 GEDCOM（.ged）文件。

首次运行会在您的主目录中创建一个保存该家谱的小数据目录（.gramps-connect-desktop）；之后的运行会复用它。删除该文件夹即可恢复为空白状态。这些都是未签名、仅支持 x86_64 的构建，因此会出现下文所述的操作系统警告——这并不表示出了什么问题。

Windows

1. 从最新发布版下载 gramps-connect-desktop-windows.zip 并解压（右键 → 全部解压缩）。
2. 打开解压后的文件夹，双击 gramps-connect-desktop.exe。
3. 由于这不是已签名的可执行文件，Windows 很可能会显示 SmartScreen 警告（“Windows 已保护你的电脑”）。点击更多信息，然后点击仍要运行。
4. 一个运行该应用的窗口会自动打开。以 admin / admin 登录。

macOS（Apple 芯片）

适用于 M1/M2/M3/M4 Mac。

1. 从最新发布版下载 gramps-connect-desktop-macos-arm64.zip 并解压（双击，或右键 → 打开，取决于您的 Mac 设置），得到 gramps-connect-desktop.app。
2. 双击 gramps-connect-desktop.app。此构建已使用 Developer ID 签名并经过 Apple 公证，因此应当可以正常打开，完全不会出现 Gatekeeper 警告。如果仍然出现，请参阅下文的故障排除。
3. 一个运行该应用的窗口会自动打开。以 admin / admin 登录。

macOS（Intel）

适用于较旧的 Intel 处理器 Mac（Apple 芯片之前）。步骤与上面的 Apple 芯片相同，只是改为下载 gramps-connect-desktop-macos-intel.zip。

Linux（.deb——Debian、Ubuntu 及其衍生版）

1. 从最新发布版下载 .deb 文件（gramps-connect-desktop_*_amd64.deb）。
2. 安装：sudo apt install ./gramps-connect-desktop_*_amd64.deb（由于是从本地文件而不是软件源安装，apt 很可能会警告该软件包未签名——这是预期的，见故障排除）。
3. 在终端中运行 gramps-connect-desktop，或在应用程序菜单中找到“Gramps Connect Desktop”。
4. 它会在自己的原生窗口中打开，使用系统中已有的 GTK3 + WebKit2（在 Linux 桌面上很常见——许多应用本来就依赖它们；本软件包不包含这两者）。如果您的系统没有它们，则会改为在浏览器标签页中打开（见故障排除）。以 admin / admin 登录。
5. 卸载：sudo apt remove gramps-connect-desktop。

Linux（.rpm——Fedora、RHEL、AlmaLinux 及其衍生版）

1. 从最新发布版下载 .rpm 文件（gramps-connect-desktop-*.x86_64.rpm）。
2. 安装：sudo dnf install ./gramps-connect-desktop-*.x86_64.rpm（在没有 dnf 的系统上，sudo rpm -i gramps-connect-desktop-*.x86_64.rpm 也可以，只是不会自动解析依赖）。与上面的 .deb 一样，从本地文件安装意味着 dnf/rpm 很可能会警告该软件包未签名——这是预期的。
3. 在终端中运行 gramps-connect-desktop，或在应用程序菜单中找到“Gramps Connect Desktop”。
4. 它会在自己的原生窗口中打开（或回退到浏览器标签页）——与上面的 .deb 相同。以 admin / admin 登录。
5. 卸载：sudo dnf remove gramps-connect-desktop。

配置

gramps-connect-desktop 无需任何配置即可工作。唯一可选的设置是外发电子邮件：默认情况下，任何会发送邮件的操作（密码重置、邮箱确认、新用户通知——虽然在单用户版本上并没有要通知的人）都会直接失败并提示“Connection was refused”，因为您的电脑上没有可供它连接的邮件服务器。要真正发送这些邮件，请在启动应用前设置以下环境变量：

变量	用途
GRAMPSWEB_EMAIL_HOST	SMTP 服务器主机名
GRAMPSWEB_EMAIL_PORT	SMTP 服务器端口（默认 465）
GRAMPSWEB_EMAIL_HOST_USER	SMTP 登录用户名
GRAMPSWEB_EMAIL_HOST_PASSWORD	SMTP 登录密码
GRAMPSWEB_DEFAULT_FROM_EMAIL	所发邮件的“发件人”地址
GRAMPSWEB_EMAIL_USE_SSL	true/false——隐式 TLS/SSL 连接
GRAMPSWEB_EMAIL_USE_STARTTLS	true/false——通过 STARTTLS 升级的普通连接
GRAMPSWEB_EMAIL_USE_TLS	true/false——较旧的别名；建议使用上面两个（默认 true，即隐式 TLS）

只有您设置的变量才会生效；未设置的项会回退到 gramps-web-api 对该选项的默认值。例如，要通过 Gmail 使用应用专用密码发送：

GRAMPSWEB_EMAIL_HOST=smtp.gmail.com \
GRAMPSWEB_EMAIL_PORT=587 \
GRAMPSWEB_EMAIL_HOST_USER=you@gmail.com \
GRAMPSWEB_EMAIL_HOST_PASSWORD=your-app-password \
GRAMPSWEB_EMAIL_USE_STARTTLS=true \
GRAMPSWEB_DEFAULT_FROM_EMAIL=you@gmail.com \
./gramps-connect-desktop

从终端运行时，--browser 会在 macOS/Windows 上跳过原生窗口，始终改在您的默认浏览器中打开——与 Linux 总是使用的回退方式相同（见架构），只是由您主动选择而不是自动发生。如果您更想使用自己浏览器的开发者工具/扩展，或者在出现异常时想排除原生 webview 的问题，这会很方便：

./gramps-connect-desktop --browser

故障排除

• Windows SmartScreen（“Windows 已保护你的电脑”）——这是预期的，因为此构建未经代码签名。点击更多信息 → 仍要运行。
• macOS Gatekeeper（“无法打开，因为 Apple 无法检查其是否包含恶意软件”）——此构建已使用 Developer ID 签名并经过 Apple 公证，所以不应发生这种情况。如果发生了，请先尝试一次性清除整个 .app 的隔离标记：xattr -cr gramps-connect-desktop.app（在终端中、在您解压它的文件夹里运行）。也请报告这个问题——这很可能意味着公证凭证在下载/解压后没有如预期那样保留下来，或者构建没有被正确公证。
• apt/dnf 警告 .deb/.rpm 未签名，或跳过了 OpenPGP 检查——这是预期的。这些软件包由本仓库自己的 CI 构建，并未发布到已签名的发行版软件源中，因此从本地文件安装时总会这样；这并不表示有什么问题。
• dnf: command not found / rpm: command not found——您的发行版基于 Debian/Ubuntu（或者出于其他原因没有提供 rpm），因此 .rpm 软件包不是合适的下载。请改为获取 .deb 文件，并用 sudo apt install ./gramps-connect-desktop_*_amd64.deb 安装（见上文的 .deb 部分）。
• 在任何平台上都没有出现窗口或浏览器标签页——一旦服务器启动，应用总会尝试自动打开一个；如果因故失败，请自己打开 http://127.0.0.1:5050。如果那里也没有任何服务在监听，说明在此之前就有东西崩溃了——请查看终端输出中的错误（Windows：在 cmd/PowerShell 窗口中运行 gramps-connect-desktop.exe，而不是双击，这样才能看到输出），并考虑附上该输出提交一个 issue。
• 应用无法启动 / 端口已被占用——同一时间只能运行一个实例（它被硬编码为 127.0.0.1:5050）。关闭其他正在运行的副本，或任何占用 5050 端口的程序，然后重试。
• 打开的是浏览器标签页而不是原生窗口——应用总是先尝试原生窗口，如果做不到就会自动回退：在 Windows 上无法使用 WebView2（Windows 10/11 默认自带），或在 macOS 上无法使用 WKWebView（始终存在），或者在 Linux 上系统中没有安装 GTK3 + WebKit2（安装 python3-gi、gir1.2-gtk-3.0 和 gir1.2-webkit2-4.1，或您发行版中的等价软件包，然后重新启动即可获得原生窗口）。无论哪种情况，应用在浏览器标签页中都能完整工作——这只影响它的呈现方式，而不影响它能做什么。
• 从一棵空白家谱重新开始——删除主目录中的 .gramps-connect-desktop 文件夹，然后重新启动。
• 想要真正的多用户部署，而不是这个单用户本地版本？ 请参阅部署。

关于数据安全，以及 gramps-connect-desktop 与 Gramps 桌面版和服务器部署的比较，另请参阅常见问题。