部署教程
Arcane 部署教程：管理 VPS 上的 Docker Compose 项目
用 Arcane 管理现有 Docker Compose 项目，保留原配置路径，设置私人入口，并备份面板数据与加密密钥。
把现有 Compose 项目接入 Arcane
一台 VPS 上跑了几个网站、订阅阅读器和数据库，每次更新都要找到对应目录，再查看容器和日志。Arcane 可以把这些操作放到浏览器里：查看容器状态、编辑 Compose、拉取镜像、管理卷和安排备份。如果已经积累了不少 Compose 项目，它比重新搬进一套面板可以少做一些重复操作。
接管前先查清：原来的配置文件在哪里，数据库究竟存在什么卷里。面板能看到正在运行的容器，不代表它已经找到了启动时使用的全部文件。路径、项目名和环境变量一旦改变，新容器可能挂上一个空目录，网站看起来就像被重新安装了一遍。
本篇使用 Arcane v2.14.0 的管理端镜像，在一台 Linux Docker 主机上建立私人入口，再逐步接入已有项目。操作范围是单机管理，不涉及迁移数据库，也不要求把现有服务统一搬到新的目录。
注册推荐码：KuZhuJi
先确定谁负责部署
如果网站已经由 1Panel、脚本或者 CI 自动部署，就不要马上让另一个面板修改同一份配置。可以先在 Arcane 查看状态和日志，继续由原来的流程更新。等到决定转交部署权，再保存原始文件、记录启动参数并验证一次完整重建。
一份 Compose 最好有明确的维护入口。今天在面板换镜像，明天 CI 又覆盖 YAML，会让实际运行状态和仓库里的配置分开。后来遇到错误时，很难判断究竟哪份文件应当用于恢复。
Arcane 会访问 Docker API，能够创建、停止和删除容器。Docker socket 挂载上 `:ro`，并不等于只能查询容器；这个标记限制挂载文件的写入方式，不能替你把 Docker API 变成只读。官方的 socket proxy 可以过滤请求，但允许创建容器和执行命令时，仍然具有很高的权限。
因此这里先把管理端口绑定到本机，通过 SSH 隧道访问。它适合自己维护一台服务器的情况，不必为了偶尔查看日志就增加一个公开面板入口。需要多人远程管理时，再按官方访问控制文档设计账号与权限，而不是共享管理员密码。
固定镜像版本，保存加密密钥
服务器需要 Docker Engine、Compose 插件和可以访问镜像仓库的网络。先检查已有环境：
docker version
docker compose version
id -u
id -g后两条命令给出当前用户的 UID 和 GID，后面用来设置文件属主。不要直接认定所有机器的普通用户都是 `1000:1000`。
建立 Arcane 自己的目录，和需要接管的项目分开放置：
mkdir -p ~/arcane
cd ~/arcane
umask 077
openssl rand -hex 32把输出的密钥保存到密码管理器，再创建 `.env`。32 字节随机数会输出为 64 个十六进制字符，属于官方支持的密钥形式。以下字段中的占位文字必须替换：
ARCANE_ENCRYPTION_KEY=REPLACE_WITH_GENERATED_HEX_KEY
ARCANE_UID=REPLACE_WITH_HOST_UID
ARCANE_GID=REPLACE_WITH_HOST_GID这个密钥用于持久化敏感配置，不能随着容器重建随意换掉。备份应用数据时，也要保留对应密钥；把它只记在面板里，服务器损坏后可能找不回来。
创建 `compose.yaml`：
services:
arcane:
image: ghcr.io/getarcaneapp/manager:v2.14.0
container_name: arcane
ports:
- '127.0.0.1:3552:3552'
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- arcane-data:/app/data
environment:
APP_URL: http://localhost:3552
PUID: ${ARCANE_UID}
PGID: ${ARCANE_GID}
ENCRYPTION_KEY: ${ARCANE_ENCRYPTION_KEY}
TZ: Asia/Shanghai
cgroup: host
healthcheck:
test: ['CMD', './arcane', 'health', '--timeout', '2s']
interval: 10s
timeout: 3s
retries: 5
start_period: 15s
restart: unless-stopped
volumes:
arcane-data:这份配置使用当前官方文档中的 `manager` 镜像名称。发行流程也保留 `arcane` 名称作为管理端镜像，两者名称不同不代表属于不同产品。这里固定 `v2.14.0`，便于记录教程使用的版本；以后更新时先看发布说明，不把 `latest` 自动拉取当作固定版本部署。
本例直接挂载 socket，明确授予单机 Docker 管理权限。需要减少 API 暴露时，按Socket Proxy 文档选择代理并核对允许的方法。不要仅加一个只读挂载标记，就把配置称为最小权限。
保存文件后执行：
cd ~/arcane
chmod 600 .env
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps配置检查不输出完整的环境变量，避免把密钥打印到终端记录。容器启动失败时查看日志；如果是项目文件权限或网络问题，先处理具体错误，不要同时放开 socket、目录权限与公网端口来试运气。
通过 SSH 完成首次登录
在自己的电脑运行下面的命令，替换用户名和服务器地址：
ssh -L 3552:127.0.0.1:3552 USER@SERVER_IP保持终端连接，浏览器访问 `http://localhost:3552`。新安装的初始账号为 `arcane`，密码为 `arcane-admin`，第一次登录会要求修改密码。改成独立的强密码后再继续配置。已经运行过的实例不能据此认定仍使用初始密码，不要为了重新登录而清空数据卷。
如果本机 3552 被占用，可以换一个本地端口；相应调整访问地址与 `APP_URL`，不要同时混用 `localhost`、IP 和几个不同的入口来排查登录问题。需要长期使用域名时，再修改 `APP_URL` 和反向代理，确保 WebSocket 连接也能通过。单纯给面板套上 HTTPS，并不会降低它操作 Docker 的权限。
进入后先查看环境设置中的更新开关，关闭自动安装更新。先保留查看镜像状态、日志和资源用量这些操作，暂时不要点击 Update All。这个按钮可能涉及当前环境里的多个服务，不能当成刷新列表使用。
准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。
原来的项目路径要原样映射
假设已有项目位于 `/srv/compose`，里面各有独立的子目录。接管前先保存 Compose、`.env`、附带的配置文件和实际数据备份，确认可以回到原来的部署方式。不要为了接入面板就改目录名称。
在 Arcane 的 Compose 中增加下面的挂载和环境变量，保留前面的其他配置：
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- arcane-data:/app/data
- /srv/compose:/srv/compose
environment:
PROJECTS_DIRECTORY: /srv/compose这是配置片段，应合并到 `arcane` 服务的同名字段，不要创建第二个 `volumes` 或 `environment`。实际项目根目录不同，就把两处路径一起替换。当前用户也需要拥有合理的读取和编辑权限；不为了让面板识别项目而给整个目录设置全员可写。
挂载应使用 `/srv/compose:/srv/compose`。容器内外使用相同的绝对路径，Docker 才能按照原来的目录解析 `./config`、`./data` 等相对挂载。写成 `/srv/compose:/app/data/projects`，面板可能读到了 YAML，但主机上的 Docker 解析文件路径时会出现差异。
如果项目分散在几个目录，可以分别原样挂载，再选择合适的项目目录范围。不要把主机整个根目录都挂进去方便搜索。目录范围越大，面板账号能够接触的文件也越多。
修改 Arcane 自己的配置后重新检查与启动，它只应重建管理端容器：
cd ~/arcane
docker compose config --quiet
docker compose up -d图中是官方文档的项目示例。实际接入时，先核对项目目录和服务，再比较面板记录与服务器上原来的配置；示例中的服务名称不对应你的服务器。
路径对上之后，还要核对 Compose 项目名。原来使用 `docker compose -p myblog` 启动的服务，不应在面板中换成另一个名字后直接重建。项目名会影响默认网络和卷名称；已有 `name:`、`external: true` 或 `COMPOSE_PROJECT_NAME` 的配置也要保留。不要为了让列表更整齐，先给数据库项目改名。
核对挂载可以查看已有容器，但检查输出可能包含敏感配置，不要完整贴到公开论坛。至少确认数据库使用的是哪一个命名卷，媒体文件是否采用主机目录，以及新配置会不会创建不同名称的卷。看到一个空数据库时，先查挂载对象是否变了，不要马上初始化覆盖。
导入现有 Compose 项目
选一个可以短暂停机、数据已经备份的小服务，确认面板能看到原来的 Compose 和环境文件，再做一次受控更新。数据库、相册和主要网站留到这一步完成之后。
部署前检查镜像、端口、挂载和环境变量是否与原来一致，更新后从真实访问地址验证页面或接口，再检查数据。日志没有报错，只能说明没有看到对应错误，不能替代打开服务确认内容。
项目文档区分了 Restart、Redeploy、Down 和 Destroy。重启现有容器与拉取镜像后重新部署不是同一件事；Destroy 还可能涉及项目文件和数据卷。看清确认框，再执行需要的动作，不要凭图标猜含义。
如果使用 Watch output 打开附着的部署窗口，也要留意关闭窗口的行为：它可能像命令行按 Ctrl-C 一样停止项目。想持续运行服务，可以使用后台执行方式，在 Activity Center 跟踪进度。另一个不应随手勾选的是重建变更卷的选项，它可能删除并重新创建卷中的数据。
原部署流程保留到这次验证完成。之后决定由 Arcane 管理，就让它成为这份配置的明确编辑入口；仍由 Git 或 CI 管理的项目，则继续在原来源修改。不要让两个流程轮流写同一份文件。
需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。
镜像检查与自动安装分开设置
自动更新会重建容器，有状态服务应先有备份和维护安排。更新文档提供单容器标签，可以在对应服务上增加：
labels:
- com.getarcaneapp.arcane.updater=false这个标签阻止 Arcane 自动安装更新，但仍可以检查并通知有新镜像。把它放在需要保护的业务服务上，不是只放在 Arcane 自己的容器上。增加标签通常需要按原来的 Compose 流程重建相应容器才能生效，安排好操作时间。
另一个标签 `com.getarcaneapp.arcane.update-check=false` 只关闭检查和通知，不能单独用它表示禁止自动安装。要完全不参与这两项功能，需要分别配置。数据库即使使用固定的大版本标签，也不能据此认定后续拉取不会变化；更新前仍应检查应用兼容性和数据恢复方案。
先从手动更新开始，确认旧镜像和旧数据怎样恢复，再为合适的无状态服务安排自动更新。面板里的更新提示可以减少查找工作，但不能替你判断一次数据库迁移是否能回退。
面板备份和业务数据备份分别保留
Arcane 的系统备份保存自己的应用数据与配置。业务容器的数据还要看具体落点：命名卷可以安排卷备份，绑定到主机目录的文件则不能因为“面板备份成功”就认定已经全部包含。
数据库和相册通常都有额外要求。数据库在持续写入时，直接复制目录可能不能得到一致的恢复点；照片系统的数据库与原片也需要配套保留。按各应用自己的备份方式生成可恢复数据，再用备份工具保存到另一处。
备份文档说明，定时卷备份可以配置备份时停止相关容器，普通的手动 Create Backup 不会自动停容器。为正在写入的业务安排卷备份时，确认采用了哪一种方式，以及停机时间能否接受。
把恢复密钥保存在 Arcane 之外。恢复密钥与部署时的 `ENCRYPTION_KEY` 有各自用途，尤其是旧备份迁移期间，不要认为生成新密钥就能解开所有历史副本。同一台 VPS 上的本地副本也不能应对整机损坏，需要复制到独立机器或配置适当的远端存储。
恢复验证先在隔离环境进行，保留原来的项目名、数据卷、挂载路径和对应配置。确认一个实际页面、几条数据库记录或几份媒体文件能够读出，再把这个流程写进维护记录。管理端停用后，原来的 Compose 仍应能够启动业务；日后更换面板或迁移服务器时，可以继续使用这些配置。