Windows 上自托管 LinkAce：从 Docker 部署到外网访问的完整实践

1. 项目概述：为什么我会在 Windows 上部署 LinkAce

1.1 LinkAce 是什么，它在解决什么问题

先说结论：LinkAce 是一套基于 Laravel 框架的开源书签管理工具，支持多用户、标签、收藏归档、全文搜索和 API 访问。把 LinkAce 部署到自己的 Windows 机器上，本质上是把散落在浏览器收藏夹、微信文件传输助手、各种"稍后读"App 里的链接，统一收进一个自己能掌控的数据库里。

很多人的收藏夹早就是一团乱麻了。浏览器收藏栏几百个条目，分类重复、命名随意，换台电脑就一片空白；偶尔想找一个之前收藏的页面，翻半天找不到，找到了还发现网站已经打不开。LinkAce 干的核心事情就是把这些链接变成"结构化数据"：每一条书签都有标题、URL、描述、标签、所属收藏集，还支持对页面内容做快照归档。收藏一个网页，它不只是一个链接，而是一条可检索、可分类、可导出的记录。

它还有一个很适合自托管的点：所有数据都在你自己的机器上，不依赖任何第三方服务。我不太喜欢把个人数据存在别人服务器上，更不喜欢哪天某个收藏工具宣布停止服务，所有数据说没就没。LinkAce 这类工具解决的不只是"整理链接"的问题，是"数据主权"的问题。

1.2 为什么选 LinkAce 而不是其他书签工具

同类开源工具其实不少，比如 Shiori、Shaarli、Wallabag、Holmes 等等。这里我不打算做大规模横向测评，只说我最终选定 LinkAce 的三个原因：

我个人的判断标准很简单：界面要能让我愿意每天用；数据结构要能让我以后随便迁走；项目要还在活跃维护。LinkAce 的 GitHub 仓库一直有更新，文档也完整，社区配套的浏览器插件和移动端方案都有成熟路径。对我来说，"能用三年以上"比"功能最花哨"重要得多。

另外多说一句，我知道有些朋友可能会直接选择 Wallabag 这类偏向"稍后读"的工具，它和 LinkAce 的定位不太一样。LinkAce 的重心在"书签管理"，而 Wallabag 的重心在"文章提取和阅读"。如果你主要需求是囤长文、做笔记，那 Wallabag 可能更合适；如果你要管理大量工具站、参考链接、日常收藏，LinkAce 的标签和收藏集机制会更顺手。

1.3 为什么用 Docker 部署而不是原生装环境

LinkAce 是 PHP 项目，依赖 Nginx/Apache、PHP 8.1+、MySQL/MariaDB 等一堆组件。在 Windows 上如果不用 Docker，等于要自己装 PHP、配 Web 服务器、搞定数据库、处理版本兼容，每一步都可能踩坑。我见过太多人卡在"PHP 扩展没开"或者"MySQL 密码问题"上，最后还没开始用就先放弃了。

Docker 的思路是把整个运行环境打包成镜像，我只需要按需下载镜像、启动容器，就能得到一个开箱即用的 LinkAce。Windows 下装 Docker Desktop 以后，compose 文件写好，一条docker compose up -d就能拉起整套服务。后续升级、备份、迁移也都围绕容器操作，干净利落。

当然，Docker 本身也不是零成本。它需要虚拟化支持，Docker Desktop 在 Windows 上默认走 WSL2 后端，第一次启动可能会遇到 BIOS 虚拟化没开、WSL2 内核版本不对等问题。这些我在后面的章节里会逐个说明，这也是这篇文章想重点解决的事：不是只告诉你"点几下就能跑"，而是让你知道每一步为什么要这么做、出问题了怎么排查。

2. 环境准备：Windows 下的 Docker 安装与配置

2.1 Docker Desktop 安装要点

我的部署环境是 Windows 11，处理器是几年前的中端配置，内存 16GB，磁盘剩余空间充足。说实话 LinkAce 对硬件要求不高，CPU 双核、内存 4GB 以上都可以跑得很流畅，但它依赖的 Docker Desktop 本身需要虚拟化能力。

安装 Docker Desktop 之前，我建议你先确认两件事：

1. 在任务管理器里切到"性能"标签，看"虚拟化"这一项是不是"已启用"。如果是"已禁用"，需要进 BIOS 开启 Intel VT-x 或者 AMD SVM，否则 WSL2 起不来，Docker 也会跟着报错。
2. 确认 Windows 版本支持 WSL2。Windows 10 需要 2004 版本以上，Windows 11 基本没问题。如果你的系统版本很老，先做一次系统更新。

到 Docker 官网下载 Docker Desktop for Windows，直接双击安装即可。安装过程中它默认会启用 WSL 相关功能，可能要求重启系统，这是正常现象。装完之后打开 Docker Desktop，等底部状态栏显示 Docker Engine running，就说明环境基础已经 OK 了。

这里有个新手常犯的误区：以为装完 Docker Desktop 就万事大吉，结果在 PowerShell 里敲docker --version提示找不到命令。Docker Desktop 的 CLI 工具默认会配置到系统 PATH，但如果安装过程中出错、或者你用的终端环境比较老（比如某些定制版 PowerShell），可能需要重新登录 Windows 或者手动检查 PATH。遇到这种情况，先重启终端，再不行就重启 Docker Desktop。

2.2 WSL2 与 Hyper-V 的选择

Docker Desktop 在 Windows 上有两个后端可以选择：WSL2 和 Hyper-V。新版 Docker Desktop 默认推荐 WSL2，这也是我实际采用的方案。

WSL2 的方案是：Windows 内置的 Linux 子系统负责跑一个轻量虚拟机，Docker 引擎在这个虚拟化环境里运行。它的优点是启动速度快、内存占用比 Hyper-V 模式略好，而且你可以同时用 WSL 干别的。对多数人来说，选 WSL2 是默认最优解。

需要注意一点：WSL2 需要下载安装 Linux 内核更新包。如果你用的是 Windows 10，安装 Docker 之后如果遇到"WSL2 kernel update is required"之类的弹窗，去微软官网下载 WSL2 Linux 内核安装包装一遍，然后wsl --set-default-version 2设置默认版本。Windows 11 24H2 之后的内置 WSL 版本一般已经不需要单独装了，但跑一遍wsl --update也没坏处。

如果你不想用 WSL2，Docker Desktop 设置里也可以切成 Hyper-V 后端，前提是 Windows 版本支持 Hyper-V 并且你不需要同时开第三方虚拟化软件（比如某些老版本 VMware 会冲突）。这个方案我一般不推荐常规用户用，除非你明确知道自己为什么需要它。

2.3 创建项目目录与准备基础文件

安装好 Docker 之后，开始创建项目目录。我习惯把所有自托管服务的目录集中放在一起，方便管理，比如D:\docker-services\linkace。为什么放 D 盘？主要是为了规避 C 盘空间不足的问题，同时备份时只需要单独处理这个目录就行。

在当前目录下新建两个文件：docker-compose.yml和.env。其中.env在 LinkAce 官方镜像里是可选的，但我建议使用它，把所有环境变量集中管理，后续改端口、改密码就不用直接动 compose 文件了。

Windows 下建议用 VS Code 或者 Notepad++ 编辑这两个文件，不建议用系统自带记事本，除非你只改字符串不换行。记事本对 UTF-8 编码和换行符的处理偶尔会捣乱，容易造成 YAML 解析报错。

在正式部署之前，在终端里先跑一次docker version，确认客户端和服务端都能正常返回版本信息。如果只显示 client 信息、server 部分报错，基本可以断定 Docker 引擎还没有完全启动，等 Docker Desktop 状态条变绿再试。

3. LinkAce 核心配置：docker-compose 逐行拆解

3.1 完整 compose 配置解读

下面是我实际使用的docker-compose.yml，你可以作为参考，我逐段解释每一段在干什么：

services: app: image: stefanzweifel/linkace container_name: linkace restart: unless-stopped ports: - "8089:80" env_file: - .env environment: - APP_ENV=production - APP_DEBUG=false - LOGIN_ALLOWED=false - TZ=Asia/Shanghai volumes: - linkace_data:/var/www/html/storage depends_on: - db db: image: mariadb:10.11 container_name: linkace_db restart: unless-stopped environment: - MYSQL_DATABASE=linkace - MYSQL_USER=linkace - MYSQL_PASSWORD=请改成强密码 - MYSQL_ROOT_PASSWORD=请改成另一个强密码 volumes: - linkace_db:/var/lib/mysql

先解释app服务。image指定 LinkAce 官方镜像，作者是项目的维护者 stefanzweifel，镜像仓库在 Docker Hub 上。container_name给容器起个固定名字，排查日志时方便。restart: unless-stopped表示只要没手动停掉，系统重启后容器会自动拉起，对于长期挂着的外部访问场景非常关键。

ports这一段，"8089:80"的含义是把宿主机 8089 端口转发到容器内的 80 端口。容器内的 Web 服务固定监听 80，宿主机端口则由我决定。选择 8089 而不是 80，是为了避开 Windows 上可能被占用的端口，也顺便避免暴露在公网上时被无差别扫描的频率太高。

env_file引入当前目录下的.env文件，数据库连接信息和应用密钥都放那里。environment里的三个变量覆盖了 compose 自带的默认值：APP_ENV=production告诉 Laravel 以生产模式运行，APP_DEBUG=false防止出错误时向前端输出敏感堆栈信息，LOGIN_ALLOWED=false关闭注册入口，后面安全加固里我会详细展开。

volumes这行是关键中的关键。LinkAce 把上传的图片、归档页面、日志等内容存放在容器内的/var/www/html/storage目录下，如果不挂载到宿主机，容器删掉重来数据就全没了。我用 Docker 命名卷linkace_data来存，容器和数据卷的关联由 Docker 自动管理，备份时也有明确目标。

db服务用了 MariaDB 10.11。为什么不直接用 MySQL？MariaDB 是 MySQL 的社区分支，和 LinkAce 的兼容性一直很好，内存占用也更友好。MYSQL_DATABASE、MYSQL_USER、MYSQL_PASSWORD这三个变量是镜像初始化数据库时用的，只要这些值和.env里 LinkAce 连接的库名、用户名、密码保持一致，应用才能连上数据库。MYSQL_ROOT_PASSWORD是数据库超级管理员的密码，生产环境里务必改一个不重样的。

3.2 关键参数解析：APP_KEY、APP_URL 与端口选择

.env文件里需要认真对待的参数有三个：APP_KEY、APP_URL、数据库连接参数。我给的.env模板长这样：

APP_NAME=LinkAce APP_ENV=production APP_KEY=请生成后替换 APP_DEBUG=false APP_URL=http://192.168.1.100:8089 DB_CONNECTION=mysql DB_HOST=db DB_PORT=3306 DB_DATABASE=linkace DB_USERNAME=linkace DB_PASSWORD=请改成强密码 DB_PREFIX=

APP_KEY是 Laravel 框架的加密密钥，用于 session、密码、加密数据的底层加解密。官方镜像第一次启动时会尝试自动生成这个值，但我遇到过没有自动生成的情况——应用报错 "No application encryption key specified"，白屏加 500 错误。我的建议是老老实实手动生成。

生成方法非常简单，终端执行：

docker run --rm stefanzweifel/linkace php artisan key:generate --show

执行后会输出一个类似base64:xxx的字符串，复制到.env的APP_KEY=后面。这一步不能省，也不要随便乱填，密钥长度不对或者格式不对会让下次启动时收到 crypt 解密相关报错。

APP_URL这个参数很多人不理解。它的作用主要是生成绝对链接：你在书签详情页里复制"共享链接"、API 返回的完整 URL、邮件通知里的链接，都会基于APP_URL来拼。如果你配了域名，就填https://你的域名；如果暂时只用局域网访问，就填你主机在当前局域网里的 IP 加端口，像我上面的http://192.168.1.100:8089。这个值在部署初期填错了问题不大，后期接入域名后改过来即可，但不建议一直不写，会导致一些导出功能生成的链接不对。

端口选择也是实践出来的教训。我原来习惯用 80 端口，后来发现 Windows 上有时候 IIS 或者其它服务会抢占 80，容器起半天端口映射不生效。改用 8089 后省了很多麻烦。还有一个加分项：如果以后你把这个服务暴露到公网，用非常规端口可以减少扫描器对"默认 Web 服务"的兴趣，虽然真正的安全不能依赖这个，但稍微降低一下被工具扫描命中的概率没有坏处。

3.3 启动、初始化管理员账号

配置写完后，第一次启动的完整流程如下：

docker compose up -d

这个命令会拉取镜像、创建网络、启动两个容器，-d表示后台运行。第一次拉镜像需要一点时间，视网络情况而定。结束后执行：

docker compose ps

看到app和db两个服务都是Up状态，就算启动成功了。如果app容器反复重启，最常见的两个原因是数据库连接不上和 APP_KEY 没生成，先看日志：

docker compose logs app

日志里会直接告诉你是连接被拒绝还是签名错误，对症下药。

LinkAce 的初始账号创建方式和很多 Laravel 项目类似，进入容器执行 artisan 命令：

docker compose exec app php artisan linkace:create-user

按提示输入用户名、邮箱、密码，回车。创建成功后打开http://localhost:8089，就能看到登录页面。因为我在 compose 里设置了LOGIN_ALLOWED=false，所以注册入口是关闭的，没有人能在你的实例上随便注册账号，第一个用户就是你刚创建的管理员。

4. 实现外部访问：从局域网到公网

4.1 先从局域网开始

很多人一上来就想让外网访问，结果连局域网都打不开，排查过程全混在一起。我的建议永远是分两步走：先把局域网访问搞定，再考虑公网。

LinkAce 容器跑起来以后，你在本机访问http://localhost:8089应该能看到页面。但同一局域网里的手机平整访问你的主机 IP，比如http://192.168.1.100:8089，很可能是打不开的，原因十有八九是 Windows 防火墙没有放行这个端口。

Windows 防火墙默认会拦截入站连接，Docker Desktop 在安装时会给自己放行一部分规则，但宿主机端口映射到容器后，外部访问宿主机的 8089 端口还是可能被拦。我用的放行命令是：

netsh advfirewall firewall add rule name="LinkAce 8089" dir=in action=allow protocol=TCP localport=8089

这条命令会新建一条入站规则，允许 TCP 端口 8089 被访问。建议用管理员权限的 PowerShell 执行。name可以随便起，但起一个能认出来的名字，后期清理规则时方便。

放行之后，手机和电脑连同一个 WiFi，在手机浏览器里访问宿主机的局域网 IP 加端口，能打开页面就说明局域网访问已经通了。这一步通了，后面再谈公网，问题的层次就清晰很多。

4.2 路由器端口映射与 DDNS 动态域名

局域网访问通了之后，想让公网也能访问，核心工作是端口映射。家庭宽带的公网入口一般在光猫和路由器上，访问http://192.168.1.1之类的管理页面，找到"端口映射""端口转发""虚拟服务器"等菜单，把公网上的某个端口映射到内网主机的 8089 端口。

一个典型的映射规则是：

注意：外部端口和内部端口可以不一样。设置好后，以后你访问http://你的公网IP:8090就能穿透到内网主机的 LinkAce。

但这里有个现实问题：大多数家庭宽带的公网 IP 是动态的，可能每几天就会变一次。每次变了你都要去查新 IP，太麻烦。解决办法是 DDNS，动态域名解析。路由器管理页面通常自带 DDNS 功能，常见的服务商有公网厂商捆绑的和第三方动态域名供应商。注册一个动态域名，把它和当前公网 IP 绑定，路由器会自动在 IP 变化时更新 DNS 记录，之后你只需要记住yourname.某域名就可以访问。

如果你的宽带本身拿不到公网 IPv4——典型的特征是路由器外网 IP 是一个 100.64.x.x 或者 10.x.x.x 的保留地址——那端口映射这条路基本走不通。这属于运营商做了大内网 NAT，不是你路由器配置能解决的。这种情况下我的建议是：不硬着头皮搞公网访问，把服务放在局域网内用，或者干脆迁移到一台有公网 IP 的云服务器上，通过云服务器反向代理到家里的机器，这是合规也稳妥的做法。

4.3 用反向代理 + HTTPS 提升访问体验

直接通过 IP 加端口访问也能用，但有两个问题：一是 IP 地址难记，证书也不好弄；二是 HTTP 明文传输，登录密码在公网上裸奔。引入域名和 HTTPS 之后，这两件事一起解决。

这里选择很多，Nginx、Caddy、Traefik 都可以。我自己的习惯是 Caddy，因为它的配置非常短，自动申请和续期证书，省掉一大半证书管理的功夫。你只需要在 Caddyfile 里写：

linkace.example.com { reverse_proxy localhost:8089 }

然后启动 Caddy，它就会自动为linkace.example.com申请 HTTPS 证书，并把请求转发到本机的 8089 端口。前提是你已经通过 DDNS 把linkace.example.com解析到当前主机的公网 IP，并且外部访问的 443 端口已经映射到运行 Caddy 的主机。

如果你更熟悉 Nginx，也可以。反向代理的关键配置是：

server { listen 443 ssl; server_name linkace.example.com; ssl_certificate /path/fullchain.pem; ssl_certificate_key /path/privkey.pem; location / { proxy_pass http://127.0.0.1:8089; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

注意proxy_set_header那几行，特别是X-Forwarded-Proto，Laravel 框架在生成 URL 时需要知道原始协议是 HTTPS，否则即使外面访问是 HTTPS，内部生成的链接还是 HTTP，导致跳转异常。这是很多"反代部署 Laravel 应用老是跳 http"问题的根源。

在设置 LinkAce 的APP_URL时，也要改成https://linkace.example.com，让应用生成的绝对链接保持 HTTPS。

4.4 安全加固，别把书签工具裸奔在公网上

外部访问打开之后，安全问题是必须单独聊的一章。LinkAce 是自托管服务，暴露在公网上意味着任何人都可以尝试访问登录页，各种扫描器也会盯上它。我的核心建议集中在几个点上：

不用数据库默认端口暴露。db服务我故意没在 compose 里写ports，这意味着容器内的 3306 端口只对 Docker 内部网络开放，宿主机和外部完全访问不到。很多人图省事把数据库端口映射到宿主机，等于给攻击者多了一把钥匙，能省则省。

关闭注册入口和强制强密码。LOGIN_ALLOWED=false可以关掉注册，但管理员密码不能因此放松。我建议管理员密码直接用密码管理器生成，16 位以上，包含大小写、数字和特殊符号。如果以后确实需要给家人或同事开账号，再临时打开注册，让对应的人注册后马上关掉，每个人建独立账号。

定期观察访问日志。LinkAce 容器日志里会记录登录请求，docker compose logs app或者查看宿主机反代日志。如果发现大量来自陌生 IP 的登录尝试，不管有没有成功，都说明有人在扫描你的服务，可以考虑在反代层做访问控制，比如只允许特定 IP 段，或加一层 HTTP Basic Auth。两层密码虽然烦，但对个人书签服务来说，多一道锁就是多一分安宁。

最后，公网访问强烈建议有 HTTPS 就用 HTTPS，没有证书至少做好访问控制。书签内容本身不一定敏感，但账号密码和登录会话一旦被人拿到，人家不仅能删你的收藏，还可能借你的服务做跳板，等于在自家机器上开了个洞。

5. 实战问题排查：部署过程中踩过的坑

5.1 Docker 起不来：端口占用和 WSL 异常

部署过程中最让人头疼的就是容器起不来。我遇到过两种典型情况。

第一种是端口被占用。Windows 自带的一些服务或者之前装的其他软件可能已经占用了 8089 端口，导致 Docker 报 "port is already allocated"。排查命令：

netstat -ano | findstr :8089

如果看到 PID，再拿 PID 去任务管理器查是什么进程占着，能停就停，不能停就换一个宿主机端口，比如 8090，改 compose 里的ports映射即可。

第二种是 WSL2 本身出问题。表现是 Docker Desktop 启动后一直转圈，docker version报错 no docker engine。通常是 WSL2 内核没有正确初始化，或者你切换过网络环境导致虚拟交换机状态异常。处理方式依次尝试：

wsl --shutdown

然后重启 Docker Desktop。如果还不行，在"设置 → 资源 → WSL 集成"里检查配置；再不行就wsl --update一次，然后重启电脑。这套组合拳能解决九成以上的 Docker 引擎异常。

5.2 外部访问不通的排查思路

外部访问不通时，不要一上来就怀疑配置，按层级从内到外排查：

最容易被忽略的是"光猫桥接"问题。很多家庭网络是"光猫 + 路由器"两层结构，如果在光猫上做端口映射只映射到路由器的 WAN 口，而路由器又把光猫的 WAN IP 当作外网入口，实际上流量到不了你的主机。正确的做法是先把光猫改成桥接模式，让路由器直接拨号获得公网 IP，然后在路由器上做端口映射；或者如果光猫管理界面允许，在光猫上直接映射到主机 IP。你在路由器上看到的 WAN IP 如果是192.168.1.x，就说明还有一层 NAT，需要先处理光猫。

用telnet或Test-NetConnection从公网去测端口通断也很有用：

Test-NetConnection 你的域名或IP -Port 8090

返回TcpTestSucceeded : True说明网络链路已经通，剩下的问题多半是应用层配置，比如APP_URL不对或者反代头没有传对。

5.3 数据备份与恢复：LinkAce 的命根子

书签工具的价值全在数据里，备份这件事必须在部署当天就做好。LinkAce 的数据分两部分：数据库和storage目录。数据库里是书签、标签、用户、收藏集的元数据，storage目录里是页面归档、缩略图、上传的图片。

用 Docker 命名卷部署后，备份的命令很简单。比如把数据库导出成 SQL 文件：

docker compose exec db sh -c 'exec mysqldump -u root -p"$MYSQL_ROOT_PASSWORD" --databases linkace' > linkace_backup.sql

这一段可能因为密码字符在 PowerShell 里被转义而出问题，更稳妥的做法是用环境变量替代。平时备份存储卷则是：

docker run --rm -v linkace_data:/data -v ${PWD}:/backup alpine tar czf /backup/linkace_storage_$(date +%Y%m%d).tar.gz -C /data .

恢复的时候，先docker compose down停掉服务，再用 tar 解包回卷或恢复到数据库容器，最后docker compose up -d启动。

我个人的习惯是每周一次数据库备份，每天一次 storage 增量同步。备份文件放到另一个磁盘甚至另一台机器上，避免主机挂了全部陪葬。这个过程看起来烦琐，但真到某天你辛辛苦苦整理的几百个链接因为一次误操作全没的时候，就会感谢当初随手写好的备份脚本。

6. 部署完以后，我的一些真实体会

LinkAce 在 Windows 上部署这件事，技术上并不算复杂，真正花时间的其实是"想清楚要怎么用"。把它跑起来，半个小时到一小时足够；但把它长期用得顺手，需要你主动调整工作流——比如浏览器收藏夹逐步迁移、定期整理标签、把"读完即扔"的链接与"长期备用"的参考链接分开管理。

我实际用了两个月之后，最大的变化是：我不再害怕换电脑，不再担心浏览器缓存被清空，也不用在钉钉群、微信收藏夹里翻历史链接了。书签就是书签，它们是数据，应该被系统地管理，而不是躺在某个 App 的角落里吃灰。

说回部署本身，Windows 上跑 Docker 做自托管服务，确实比 Linux 服务器多一点小麻烦，但完全可接受。Docker Desktop 已经帮你解决了很多底层的兼容问题，选对端口、配好防火墙、设置好 DDNS，LinkAce 完全可以稳定跑上很长时间。

最后再分享一个小技巧：LinkAce 的 API 是很好用的，你可以用一个简单的脚本把"当前浏览器里的临时标签页"自动批量丢进 LinkAce，加上统一的"待整理"标签，然后隔一段时间集中处理一次。这套流程让我的收藏习惯从"随手存"变成了"有节奏地收集、每周清理"，效率提升非常明显。部署完之后，不妨也试试把 API 用起来。