Linkwarden 自托管：三容器部署、归档落盘与权限边界

Linkwarden 是一款按 AGPL-3.0 发布的自托管书签管理器。它在你保存链接的同时把整页存档，并提供集合共享与成员权限。下面按部署、落盘、协作、局限四段拆开讲，版本以 2.17.0 为准。

三个容器，三种职责

官方 docker-compose.yml 放在仓库根目录，只编排三个服务。应用镜像来自 ghcr.io，端口映射 3000:3000；数据库是 postgres:16-alpine；搜索是 getmeili/meilisearch:v1.13.3。三者用 depends_on 串起来，应用放在末尾启动。

组件多的代价是要多维护两个容器，好处是每个都能单独替换。不想跑搜索，把 meilisearch 从 compose 与 depends_on 里删掉即可，官方文档明确写了它是可选件。

硬件口径比想象中宽松。文档给的门槛是 4GB 内存、2 核 CPU、镜像约 1.5GB；2.15 版本重写镜像后，空载内存从约 700MB 降到约 350MB。x86-64 与 ARM64 都发镜像，NAS 和 ARM 小主机能跑。

起步只要两步：拉下 compose 与 .env.sample，改完变量后执行 docker compose up -d。首次启动要等数据库初始化，之后访问 3000 端口注册账号。

环境变量与卷：四个值必须改

必改项只有四个。环境变量文档写明：NEXTAUTH_URL 要带 /api/v1/auth 后缀，写错会让登录回调失败；NEXTAUTH_SECRET 用来签会话与归档令牌；POSTGRES_PASSWORD 是内置数据库的口令；MEILI_MASTER_KEY 决定应用是否初始化搜索客户端。

三个卷各管一件事。./pgdata 存 PostgreSQL 数据；./data 映射到容器内的 /data/data，存归档、预览与上传文件；./meili_data 存搜索索引。备份时三个目录要一起带走，缺一个恢复出来就是残缺的。

对象存储是可选项。SPACES_ENDPOINT、SPACES_REGION、SPACES_KEY、SPACES_SECRET 四个都填才会切到 S3，缺一个就继续落在本地磁盘。用 MinIO 这类自建服务时，还要打开 SPACES_FORCE_PATH_STYLE。

还有一个容易忽略的默认值。NEXT_PUBLIC_ADMIN 默认是 1，指初次注册的那个账号；实例先对公网开放再注册，管理员就会落到别人手里。文档建议先把号建好，或者显式指定用户 ID。

保存一条链接，会落下几份文件

一次保存会生成多种归档。截图、PDF、单文件 HTML 与可读正文各存一份，预览图始终生成。单文件 HTML 由 monolith 产出，那是编译进镜像的 Rust 工具；可读正文是从页面抽出的纯文本，搜索与高亮都依赖它。

这些文件都落在 STORAGE_FOLDER 下，与数据库分开存放。每种格式都有体积上限：PDF、截图、单文件 HTML 默认各 100MB，预览图 10MB，超限的产物直接丢弃而不入库。想卡住磁盘增长，把这几个值调小是直接的办法。

生成任务由后台 worker 排队完成。单条任务的浏览器超时是 5 分钟，每批处理 5 条链接，队列空 60 秒后关闭浏览器。这两个默认值既决定积压时多久能出图，也决定高峰期的内存峰值。

格式可以按需关掉。在设置里的 Archive Settings 勾选即可，单个标签还能覆盖全局设置，例如只给某类链接留完整归档。关掉 PDF 与单文件 HTML 收益明显，这两项对 CPU 与磁盘的消耗更高。

登录后才能看的页面有另一条路。扩展保存时勾上 Upload image from browser，截图在你的浏览器里完成再上传，服务端不再去解压页面。SingleFile 扩展也能直接传自包含的 HTML，受 10MB 的 NEXT_PUBLIC_MAX_FILE_BUFFER 限制。

扩展、公共集合与三种角色

浏览器扩展本身也开源，Chrome、Brave、Edge 走 Chrome Web Store，Firefox 走 Add-ons，Safari 走 Mac App Store。扩展文档写明首次使用要填三项：实例地址、用户名或邮箱、密码。2.17 之后在地址栏输 lw 加空格，可以直接搜自己的收藏。

集合相当于文件夹，但每个链接只属于一个集合，未指定时进 Unorganized。集合能嵌套，也能公开。公开后得到一个 /public/collections/<id> 形式的链接，未登录的人能读、能搜、能按标签筛，还会顺带生成 RSS。

公开是有代价的。公共集合页面会列出成员的用户名，不只是链接本身；子集合不会跟着父集合一起公开，得逐个打开。集合文档对此写得很直白：加成员前要确认对方可信。

成员权限分三档。Viewer 只能读；Contributor 能新增链接；Admin 能增删改任意链接并创建子集合。改名、换图标、管成员、开关公开、删除集合这几件事始终归 owner，角色再高也拿不到。

成员一加进来就能读到归档内容，包括已存下的整页副本。把人降级成 Viewer 不会收回他已经看过的内容，这是权限模型本身的边界。站内那篇自托管 Wiki 对比讨论的授权粒度问题，在这里同样适用。

局限：索引、存储与移动端

搜索索引是派生物，不是数据的本体。Meilisearch 里存的是回灌出来的检索结构，每批 50 条，等待索引任务完成的超时默认 1000000 毫秒。索引卷丢了或换了 master key，就得从头回灌一遍，链接越多等得越久。

不想维护这套索引也有退路。把 meilisearch 服务删掉并清空 MEILI_MASTER_KEY，搜索会退回 PostgreSQL，只匹配标题、URL、描述与标签名。代价是失去页内全文与高级检索语法，收藏量上去以后差别会很明显。

存储只涨不缩。关掉某种格式只影响之后保存的链接，历史文件不会自己变小；PDF 与单文件 HTML 是大头，一篇长文就能占掉几兆。数据库本身也会长，TEXT_CONTENT_LIMIT 控制每条链接在库里保留多少正文字符。

内存读数要看峰值，不要看空载。导入或大批量归档之后，内存会停在一个更高的位置不再回落，那是运行时与分配器留住的页，不算泄漏。按峰值选机器，或者用 MALLOC_ARENA_MAX 与 NODE_OPTIONS 压一压。

移动端是官方原生应用，iOS 与 Android 都有，APK 另放在 builds 仓库。2.17 把保存流程改成新的 link sheet，能在存之前设好名称、集合、标签、描述与封面，长列表也改成按需渲染。归档仍在服务端排队，手机端看到的是结果而不是过程。

还有一条属于使用习惯。它替代不了稍后读工具的排版，也不做文档 OCR。真要处理扫描件与票据，站内那篇 Paperless-ngx 归档更对口，两者可以并存。

适合谁，怎么起步

适合的人群比较明确：几个人要共享一份资料库、需要在原页面消失后仍能拿出证据、手上有一台常开的 NAS 或小主机。一个人用也成立，只是三容器的维护成本不会因为人少而变低。

不建议的情况同样清楚：只想快速收藏、不愿碰反向代理与证书、磁盘只有几十 GB。这类需求用浏览器自带书签或云端服务更省事。

起步顺序建议按这个走。

1. 先只起应用与数据库，把端口和三个目录定在空间充足的位置。
2. 注册账号，确认能进管理界面，再把 NEXT_PUBLIC_DISABLE_REGISTRATION 改成 true。
3. 接上反向代理与 HTTPS，把 NEXTAUTH_URL 换成正式域名，重启后验证登录回调。
4. 定下归档格式，导入一批旧书签观察磁盘与内存，再决定是否加 Meilisearch。
5. 把三个目录写进备份任务，站内那份自建备份工具清单可以直接照搬。

做完这些再考虑扩展与公开集合。顺序反了会返工，域名与 NEXTAUTH_URL 尤其如此，改一次就要重启一次。

相关地址

以下为文中项目的官方入口，版本号、文档与下载以这些页面为准。

• Linkwarden（GitHub 仓库）：https://github.com/linkwarden/linkwarden
• Linkwarden（官网）：https://linkwarden.app/
• Linkwarden（文档站）：https://docs.linkwarden.app/
• Linkwarden（浏览器扩展仓库）：https://github.com/linkwarden/browser-extension