Docker 部署指南：5 分钟完成搭建

2025-03-18 安全与部署

MarkStackAI 设计之初就以简单部署为目标。得益于 SQLite 零依赖数据库和前后端分离的架构，你可以在任何支持 Docker 的环境中快速启动一个完整的实例。本文将从 Docker Compose 一键部署讲起，同时覆盖手动部署和 NAS 部署方案。

前置条件

开始之前，请确保你的服务器已安装以下软件：

Docker 20.10 或更高版本
Docker Compose v2.0 或更高版本（Docker Desktop 已内置）
磁盘空间：至少 500MB 可用空间（镜像约 300MB + 数据存储）

如果你的服务器尚未安装 Docker，可以通过官方一键脚本安装：

curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker

环境变量配置

在项目根目录创建 .env 文件，配置以下关键环境变量：

# 安全密钥（必须修改！生产环境使用强随机字符串）
SECRET_KEY=your-random-secret-key-at-least-32-chars

# 管理员初始密码（首次启动时创建 admin 用户）
ADMIN_PASSWORD=your-strong-admin-password

# 运行模式（生产环境设为 false，关闭 API 文档和调试信息）
DEBUG=false

# 端口映射
BACKEND_PORT=8001
FRONTEND_PORT=5173

# 可选：是否允许公开注册
ALLOW_PUBLIC_REGISTER=false

SECRET_KEY 必须修改为强随机字符串。如果检测到默认弱密钥，应用将拒绝启动。你可以使用 openssl rand -hex 32 生成一个安全的密钥。

Docker Compose 一键启动

这是最推荐的部署方式。项目已提供 docker-compose.yml 文件，只需三条命令即可完成部署：

# 1. 克隆项目
git clone https://github.com/markstackai/markstackai.git
cd markstackai

# 2. 配置环境变量
cp .env.example .env
vim .env  # 修改 SECRET_KEY 和 ADMIN_PASSWORD

# 3. 启动服务
docker compose up -d

启动完成后，访问 http://你的服务器IP:5173 即可看到 MarkStackAI 界面。使用 admin + 你设置的 ADMIN_PASSWORD 登录管理后台。

验证服务状态

# 查看容器运行状态
docker compose ps

# 查看后端日志
docker compose logs backend -f

# 查看前端日志
docker compose logs frontend -f

正常启动后，你应该看到两个容器处于 Running 状态。后端日志会显示 Uvicorn running on 0.0.0.0:8001，前端日志会显示 Nginx 启动成功。

手动部署方案

如果你不想使用 Docker，也可以直接在服务器上手动部署。

后端（Python 3.11+）

# 创建虚拟环境
cd backend
python3.11 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
vim .env

# 启动服务（生产环境推荐使用 Supervisor 管理进程）
uvicorn app.main:app --host 0.0.0.0 --port 8001

前端（Node.js 18+）

cd frontend

# 安装依赖
npm install

# 构建生产版本
npm run build

# 使用 Nginx 托管 dist 目录
# 或直接使用 Node.js 开发服务器（仅测试用途）
npm run preview

生产环境建议使用 Nginx 反向代理前端静态文件和后端 API。前端的 dist 目录包含构建后的所有静态资源，Nginx 将 /api 请求转发到后端的 8001 端口。

NAS 部署

MarkStackAI 的低资源需求使其非常适合在 NAS 上运行，如群晖（Synology）、威联通（QNAP）等。

群晖 Docker 部署

在群晖的 Container Manager（原 Docker 套件）中，进入"项目"页面
点击"新建"，选择"从 docker-compose.yml 创建"
粘贴项目提供的 docker-compose.yml 内容
在环境变量设置中填写 SECRET_KEY 和 ADMIN_PASSWORD
映射数据卷到 NAS 的共享文件夹（建议 /docker/markstackai/data）以便持久化 SQLite 数据库
点击启动即可

威联通用户可以通过 Container Station 完成类似操作。其他支持 Docker 的 NAS 系统（如 TrueNAS SCALE、OpenMediaVault）同样适用。

最低硬件要求

CPU：1 核心（推荐 2 核心）
内存：512MB（推荐 1GB，金融数据代理功能会占用额外内存）
磁盘：500MB（镜像 + 基础数据）；实际数据增长取决于书签和笔记数量
网络：需要外网访问能力（健康检测、金融数据获取需要请求外部 API）

一台 1 核 1GB 的云服务器即可流畅运行 MarkStackAI，非常适合个人使用。如果有多用户需求或大量书签（超过 10000 条），建议升级到 2 核 2GB。

HTTPS 配置建议

生产环境强烈建议启用 HTTPS。最简单的方式是使用 Caddy 或 Nginx + Let's Encrypt 做反向代理：

# Caddyfile 示例
bookmarks.yourdomain.com {
    reverse_proxy localhost:5173
}

Caddy 会自动申请和续期 SSL 证书，零配置实现 HTTPS。如果使用 Nginx，可以配合 certbot 工具自动管理 Let's Encrypt 证书。MarkStackAI 后端已设置 HSTS 头（max-age=31536000），浏览器会强制使用 HTTPS 连接。

生产环境注意事项

非 root 运行：Docker 容器内部以 appuser 非 root 用户运行，限制容器被攻破后的影响范围
定期备份：SQLite 数据库文件位于 data/ 目录，定期备份此目录即可。推荐使用 cron 定时任务 + rsync 异地备份
日志监控：后端日志采用 JSON 格式，可以接入 ELK 或 Loki 进行集中分析
更新升级：docker compose pull && docker compose up -d 即可完成滚动更新
数据目录权限：SQLite 数据目录权限设置为 0o700，仅容器内用户可读写

从 docker compose up -d 到浏览器打开管理界面，整个过程通常不超过 5 分钟。SQLite 零依赖的设计意味着你无需配置 MySQL、PostgreSQL 或 Redis，一个容器就是一个完整的服务。