主题
快速开始
OneTap 是一个免费开源的 Docker 管理平台，面向 NAS 场景，统一管理容器、镜像与 Compose 编排。应用市场支持一键部署常用应用；自动化组合可一键部署影视、漫画、书籍、音乐、刷流等整套工作流，并自动完成应用间的联动配置。源码托管在 GitHub，可自行部署、修改和分发。
支持范围
目前安装只支持 x86 的机器，ARM 设备尚未测试。运行环境仅支持 Linux、飞牛 fnOS、群晖这类标准 Docker 环境，其他环境暂未验证。
一、安装部署
OneTap 由应用容器和 PostgreSQL 16 数据库组成，使用 Docker Compose 一次部署。不需要 .env，也不用提前创建 data、appdata、postgres 等目录。
1、部署 OneTap
下面以飞牛 fnOS 为例。进入「Docker → 创建项目」：
- 项目名称：填写
one-tap - 路径：选择一个存储空间下的目录，例如
存储空间 1/我的文件/docker/one-tap，Compose 文件和 OneTap 数据都放在这里 - 来源：选择「创建 docker-compose.yml」，把下面的内容粘贴进去
- 勾选「创建项目后立即启动」，点击「确认」
yaml
name: onetap
services:
postgres:
container_name: onetap-postgres
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_DB: onetap
POSTGRES_USER: onetap
POSTGRES_PASSWORD: onetap9527
TZ: Asia/Shanghai
volumes:
- ./postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U onetap -d onetap"]
interval: 5s
timeout: 5s
retries: 20
start_period: 10s
app:
container_name: onetap-app
image: ccr.ccs.tencentyun.com/one-tap/one-tap:latest
restart: unless-stopped
init: true
stop_grace_period: 30s
depends_on:
postgres:
condition: service_healthy
ports:
- "6782:80"
environment:
APP_NAME: OneTap
TZ: Asia/Shanghai
DATA_ROOT: /data
DATABASE_URL: postgresql+asyncpg://onetap:onetap9527@postgres:5432/onetap
volumes:
- ./data:/data
- ./appdata:/appdata
- /var/run/docker.sock:/var/run/docker.sock启动完成后，访问 http://<主机地址>:6782。端口 6782 可以按需修改，冒号左侧是宿主机端口，右侧 80 是容器内端口，不要改动。
镜像地址
示例使用腾讯云镜像 ccr.ccs.tencentyun.com/one-tap/one-tap:latest，也可以换成 Docker Hub 上的 free5104/one-tap:latest，两者同步发布。需要固定版本时把 latest 换成对应版本标签。
目录挂载说明
挂载写法统一为 宿主机路径:容器内路径。冒号左侧可以使用相对于 Compose 文件的路径，右侧是容器内的绝对路径。
| Compose 中的写法 | 作用 |
|---|---|
./data:/data | OneTap 自身数据目录：Compose 工作区、应用图标、登录签名密钥 |
./postgres:/var/lib/postgresql/data | 数据库目录：账号、系统设置、应用实例与部署记录 |
./appdata:/appdata | 应用数据目录：各应用的配置、数据库附件、缓存等持久化小数据 |
/vol2/1000/OneTap:/mnt/hdd-1 | 业务数据目录（可选）：视频、音乐、下载等大文件 |
安全提示
必须挂载 /var/run/docker.sock，否则 OneTap 无法部署应用和管理 Docker。但这相当于把宿主机 root 权限交给它，所以不要直接暴露到公网，远程访问请使用 VPN。
2、注册管理员并登录
系统检测到还没有用户时会进入注册界面。首个注册的用户自动成为管理员，注册成功后会自动关闭注册功能。
- 密码至少 8 位
- 需要继续注册时，由管理员通过
REGISTRATION_OPEN重新开启；之后注册的用户均为普通用户
注册完成后，使用刚创建的账号登录：
建议勾选「记住我」以免频繁登录。忘记密码时页面只提供提示，没有自助重置入口，需要联系管理员处理。
3、基础设置
登录后先完成下面三项，再安装应用。
设置存储目录
进入「系统设置 → 存储配置 → 新增目录」，把 Compose 里挂载的目录登记进来。标记为「应用数据目录」的那条对应 ./appdata，之后安装的容器应用会自动放到这个目录下，并按 应用数据目录/<实例名>/<应用名>/<子目录> 生成子目录。
| 字段 | 填写内容 |
|---|---|
| 宿主机路径 | 宿主机上的绝对路径，如 /vol1/1000/docker/one-tap/appdata |
| 容器内路径 | Compose 冒号右侧的路径，如 /appdata |
- 「应用数据目录」全局只能有一条。没有配置时，应用可以预览 Compose，但正式部署会被阻止。
- 其他存储空间可以各登记一条，例如
/vol2/1000/OneTap → /mnt/hdd-1，安装应用时就能选择这些目录。 - 所有目录都必须先挂载进 OneTap 容器，页面才会显示「可见」；只在宿主机创建目录不够。
- 目录不能重叠：登记了
/vol1/1000/docker/one-tap/appdata后，不要再把它的子目录单独登记为另一条存储。
修改路径不会自动搬迁文件，更换目录前先备份并手动迁移。更多规则见系统设置 → 存储配置。
设置服务端口
在「系统设置 → 服务端口」设置服务起始端口（默认 10000）。安装部署应用时，平台从这个端口开始按顺序分配，并自动跳过已占用的端口，不需要手动记端口。
下方是 Docker 端口占用列表，部署前可以先确认某个端口是否被占用。部分应用使用固定端口（如 Jellyfin 的 8096），模板会保留固定端口并检查冲突。
设置统一账号
在「系统设置 → 基础配置 → 统一服务账号」填写管理员用户名和密码。自动化组合部署时，平台会用这组账号密码自动初始化各应用，把它们统一成同一个：
- 管理员用户名：默认
admin - 邮箱后缀：用于必须邮箱登录的应用（Komga、二毛读书），会拼成
admin@example.com - 管理员密码：留空则每次部署随机生成，建议部署完成后在应用内及时修改
该配置只对自动化组合部署生效，应用市场的单应用部署不会自动配置账号。密码用于登录应用并写回实例配置，请妥善保管。
二、部署第一个应用
完成基础设置后，先部署一个简单应用熟悉流程：应用市场 → 安装 → 填写端口与存储路径 → 在「任务中」查看进度 → 回到服务概览点击卡片访问。
熟悉之后可以继续：
升级
Compose 部署直接拉取新镜像并重建容器，数据库迁移会在启动时自动执行：
bash
docker compose pull
docker compose up -d需要升级到指定版本时，先把 docker-compose.yml 中的镜像标签改掉，再执行上述命令。升级前建议备份 data、appdata 与 postgres 三个目录，不要删除 postgres。
应用市场模板更新不会直接改动已部署实例：单应用可在服务概览的应用详情里手动升级，自动化实例组在组合页面「升级方案」，授权版还可以开启自动更新。