企业官网建设流程全解析

1. 为什么要在 Linux 上源码部署 DeepSeek Harness Web

1.1 这个项目到底解决什么问题

DeepSeek Harness Web 本质上是一套面向大模型调用链路的编排与测试面板，它把模型接入、提示词调试、会话管理、结果回放这些零散环节收拢到一个浏览器界面里。官方通常只提供容器镜像或托管服务，但真实的生产环境里，很多团队的内网机器根本拉不了外部镜像，或者安全策略不允许跑未知来源的容器。这时候源码部署就成了唯一可行的路子。

我在给几个做私有化交付的团队做支持时，反复遇到同一个场景：客户给了一台 Rocky 9 或者 Debian 13 的裸机，能连内网源，但没有任何容器运行时，也没有公网出口。你要在这种机器上把 Harness Web 跑起来，还要让同网段的同事能通过浏览器访问，靠的就是源码编译加 systemd 托管这一套组合拳。这套流程跑通之后，你得到的不是一个临时进程，而是一个开机自启、崩溃自拉、日志可查的常驻服务，这才是能交付的状态。

适合读这篇的人有三类：一是刚接触 Linux 服务部署、想拿一个真实项目练手的运维新人；二是需要在离线环境里搭大模型调试面板的算法工程师；三是手里有香橙派、旧笔记本这类设备，想把它改造成内网 AI 工具入口的折腾党。不管你基础如何，只要你能敲命令、能看懂报错，这篇里的步骤都能照着复现。

1.2 源码部署相比容器部署的取舍

很多人第一反应是"有镜像为什么不用镜像"。容器确实省事，但在下面这几种情况下，源码部署反而更稳。

第一是依赖可控。容器镜像里的 Python 版本、系统库版本是打包时定死的，你机器上的 glibc 或者 OpenSSL 跟镜像对不上，就会出现各种诡异的动态链接错误。源码部署时依赖是现装的，跟本机环境天然匹配。

第二是排障方便。容器里出问题，你得进容器、看日志、改配置、重新打镜像，链路很长。源码部署下，进程、配置、日志都在宿主机上，journalctl一拉就能看到全部输出，改完配置systemctl restart就生效。

第三是资源占用。Harness Web 本身不跑推理，它只是个前端加调度层，内存占用通常在几百 MB 级别。为这么点负载去装一整套容器运行时，对边缘设备来说不划算。

当然代价也有：你得自己管 Python 环境、自己写 systemd 单元、自己处理依赖冲突。下面我会把这些坑一个个填平。

1.3 整体架构与数据流向

在动手之前，先把整个链路在脑子里过一遍，后面每一步你才知道自己在干什么。

浏览器发起请求，打到 Harness Web 监听的端口上；Harness Web 进程收到请求后，根据配置去调用后端的模型接口（可以是本地推理服务，也可以是内网的其他模型网关）；拿到结果后渲染回浏览器。整个过程中，Harness Web 自己不存模型权重，它只是个"中间人"。

所以部署的核心就三件事：让 Python 环境能跑起来这个项目、让进程能稳定常驻、让外部能访问到这个端口。理解了这三点，后面所有操作都是围绕它们展开的。

2. 部署前的环境准备与依赖梳理

2.1 系统版本与硬件底线

先说你得有什么。操作系统这块，Rocky 9、Debian 12/13、Ubuntu 22.04 及以上都没问题，内核版本建议 5.10 以上。我实测下来 Rocky 9 最省心，因为它的 systemd 版本够新，Python 3.9 起步，装依赖不容易缺东西。Debian 13（Trixie）也完全可用，但要注意它的源要换成国内镜像，否则装包能等到你怀疑人生。

硬件方面，纯跑 Harness Web 的话，2 核 4G 是底线，4 核 8G 比较舒服。磁盘留 20G 以上，因为 Python 依赖加上日志会慢慢涨。如果你打算在同一台机器上再跑本地推理，那配置得另算，本文不展开。

网络这块要提前确认两件事：一是机器能不能访问 Python 包源（内网源或公网源都行），二是你打算暴露的端口有没有被防火墙拦着。这两点没确认就开干，后面大概率卡在半路。

2.2 系统基础依赖一次性装齐

很多人部署失败不是因为项目本身难，而是系统缺了编译工具链。Python 有些包是带 C 扩展的，没有 gcc 和开发头文件，pip 装到一半就报错。所以第一步先把基础依赖装全。

Rocky 9 下这样操作：

sudo dnf groupinstall -y "Development Tools" sudo dnf install -y python3 python3-pip python3-devel git curl wget openssl-devel libffi-devel bzip2-devel sqlite-devel

Debian 13 下换成：

sudo apt update sudo apt install -y build-essential python3 python3-pip python3-venv python3-dev git curl wget libssl-dev libffi-dev libbz2-dev libsqlite3-dev

这里有个细节值得说：python3-devel（Debian 下叫python3-dev）必须装，它提供 Python.h 头文件，没有它任何带 C 扩展的包都编译不了。openssl-devel和libffi-devel是给加密和外部函数调用用的，Harness Web 调模型接口时会用到。sqlite-devel是因为项目默认用 SQLite 存会话记录，缺了它运行时会报找不到模块。

提示：如果你用的是国产 Linux 发行版，包名可能略有差异，用dnf search或apt search先确认一下再装，别硬套命令。

2.3 Python 版本选择与虚拟环境隔离

Harness Web 对 Python 版本有要求，一般 3.9 到 3.11 之间最稳。3.12 有些依赖还没跟上，容易出兼容问题。先确认版本：

python3 --version

如果系统自带的版本太低（比如 3.6），你就得自己编译一个新版本，或者用发行版提供的更高版本包。Rocky 9 默认是 3.9，够用；Debian 13 默认 3.11，也够用。

接下来是虚拟环境。这一步千万别省，直接往系统 Python 里装依赖，早晚会把系统工具搞崩。创建虚拟环境：

cd /opt sudo mkdir -p deepseek-harness sudo chown $USER:$USER deepseek-harness cd deepseek-harness python3 -m venv venv source venv/bin/activate

激活之后，你的命令行前面会出现(venv)前缀，说明后续所有 pip 操作都只影响这个隔离环境。这个习惯养成之后，你以后部署任何 Python 项目都不会再污染系统环境。

2.4 源码获取与目录规划

源码获取方式取决于你拿到的形式。如果是 git 仓库，直接 clone；如果是压缩包，解压到/opt/deepseek-harness下。我建议的目录结构是这样的：

/opt/deepseek-harness/ ├── venv/ # 虚拟环境 ├── app/ # 源码目录 ├── data/ # 数据与 SQLite 文件 ├── logs/ # 应用日志 └── .env # 环境变量配置

把数据和代码分开，好处是将来升级代码时，直接替换app目录就行，data和logs原封不动。这个习惯在多次迭代后能帮你省下大量迁移时间。

3. 依赖安装与配置文件的正确写法

3.1 依赖安装的两种路径与踩坑点

进入源码目录后，先看有没有requirements.txt。有的话直接：

pip install --upgrade pip pip install -r requirements.txt

如果项目用的是pyproject.toml，那就：

pip install --upgrade pip pip install .

这里最容易踩的坑是网络慢导致超时。解决办法是换源，比如：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

但要注意，换源只解决下载速度，不解决版本冲突。如果装到一半报某个包版本不兼容，别急着一个个手动降级，先看报错里提到的两个包，通常把其中一个锁到兼容版本就行。我遇到过pydantic和fastapi版本打架的情况，把pydantic锁到 2.x 的某个具体小版本就解决了。

还有一种情况是某个包在 PyPI 上没有对应你系统架构的预编译 wheel，pip 会尝试从源码编译，这时候如果缺系统库就会失败。报错里一般会明确告诉你缺哪个.h文件，回去补装对应的-devel包即可。

3.2 环境变量与配置文件详解

Harness Web 的配置一般通过环境变量或.env文件注入。常见的配置项包括监听地址、端口、数据库路径、模型接口地址和密钥。一个典型的.env长这样：

HOST=0.0.0.0 PORT=8080 DATABASE_URL=sqlite:////opt/deepseek-harness/data/harness.db MODEL_BASE_URL=http://127.0.0.1:11434 MODEL_API_KEY=your-key-here LOG_LEVEL=info

这里每一项都有讲究。HOST设成0.0.0.0是为了让外部能访问，如果你只写127.0.0.1，那就只有本机能连，远程访问会失败，这是新手最常犯的错。PORT选一个没被占用的，用ss -tlnp | grep 8080先查一下。DATABASE_URL里的路径要用绝对路径，SQLite 对相对路径的处理在不同工作目录下结果不一样，容易找不到库文件。

MODEL_BASE_URL指向你的模型服务。如果你本地跑了推理服务，就填本地地址；如果走内网网关，就填网关地址。MODEL_API_KEY如果模型服务不需要鉴权，可以留空，但建议还是填个占位符，避免某些代码路径判空出错。

注意：.env文件里不要写注释在值后面，有些解析库会把注释也当成值的一部分，导致配置莫名其妙失效。要写注释就单独占一行。

3.3 数据库初始化与目录权限

如果项目需要初始化数据库，通常在源码目录下会有迁移脚本或初始化命令，比如：

python -m app.init_db

或者用 Alembic 之类的工具：

alembic upgrade head

执行之前，确保data目录存在且当前用户有写权限：

mkdir -p /opt/deepseek-harness/data chmod 750 /opt/deepseek-harness/data

权限这块我踩过一次坑：用 root 跑了一次初始化，生成的 SQLite 文件属主是 root，后来用普通用户跑服务时死活写不进去，报attempt to write a readonly database。所以从一开始就用普通用户操作，别图省事全程 root。

4. 用 systemd 把服务管起来

4.1 为什么必须用 systemd 而不是 nohup

很多人图省事，直接nohup python main.py &就完事了。这样跑起来确实能访问，但问题一堆：机器重启后服务不会自动起来；进程崩了没人拉；日志散落在nohup.out里越滚越大；想改配置得先找到进程号再 kill。这些在个人玩具项目上能忍，一旦要交付就是灾难。

systemd 把这些事全包了。它负责开机自启、崩溃重启、日志归集、资源限制、依赖管理。你写一个单元文件，剩下的交给它。这也是为什么热词里systemd出现频率那么高，它是 Linux 服务托管的事实标准。

4.2 编写一个健壮的 service 单元

在/etc/systemd/system/下新建deepseek-harness.service：

[Unit] Description=DeepSeek Harness Web Service After=network-online.target Wants=network-online.target [Service] Type=simple User=harness Group=harness WorkingDirectory=/opt/deepseek-harness/app EnvironmentFile=/opt/deepseek-harness/.env ExecStart=/opt/deepseek-harness/venv/bin/python -m app.main Restart=on-failure RestartSec=5 StandardOutput=journal StandardError=journal SyslogIdentifier=deepseek-harness [Install] WantedBy=multi-user.target

逐项解释一下关键配置。After=network-online.target保证网络就绪后再启动，否则服务可能在网络还没起来时就去连模型接口，直接失败。User和Group指定运行身份，别用 root，最小权限原则。WorkingDirectory很重要，很多项目用相对路径读配置，工作目录不对就找不到文件。EnvironmentFile把.env注入进来，这样配置和单元文件分离，改配置不用动 systemd。

Restart=on-failure配合RestartSec=5实现崩溃后 5 秒重拉。注意是on-failure不是always，这样你手动systemctl stop时它不会又自己起来。StandardOutput=journal把输出交给 journald 管理，日志自动轮转，不用你操心。

4.3 创建专用用户与权限收敛

上面单元文件里用了harness用户，得先建出来：

sudo useradd -r -s /sbin/nologin -d /opt/deepseek-harness harness sudo chown -R harness:harness /opt/deepseek-harness

-r表示系统用户，-s /sbin/nologin禁止登录，-d指定家目录。这样这个用户只能用来跑服务，不能拿来登录系统，安全性更好。把整个项目目录的属主给它，服务运行时才有权限读写数据和日志。

4.4 启动、自启与状态检查

单元文件写好后，按顺序执行：

sudo systemctl daemon-reload sudo systemctl enable deepseek-harness sudo systemctl start deepseek-harness sudo systemctl status deepseek-harness

daemon-reload是让 systemd 重新读取单元文件，每次改完单元文件都要执行。enable是设置开机自启。status看运行状态，正常的话你会看到绿色的active (running)。

如果状态是failed，别慌，直接看日志：

journalctl -u deepseek-harness -n 100 --no-pager

-n 100看最近 100 行，--no-pager防止进入分页模式。日志里通常会明确告诉你哪一行报错、缺什么模块、端口是不是被占用。我遇到最多的是ModuleNotFoundError，基本都是虚拟环境路径写错，或者依赖没装全。

5. 远程访问打通与防火墙配置

5.1 监听地址与端口占用排查

远程访问不通，九成是监听地址的问题。回到.env，确认HOST=0.0.0.0。如果这里写的是127.0.0.1，那服务只监听本地回环，外部怎么连都连不上。改完重启服务：

sudo systemctl restart deepseek-harness ss -tlnp | grep 8080

ss的输出里，如果看到0.0.0.0:8080或者*:8080，说明监听正确；如果看到127.0.0.1:8080，那就是配置没生效，检查是不是改错了文件或者没重启。

端口被占用也是常见问题。如果ss显示端口已经被别的进程占了，要么换端口，要么把占用进程停掉。换端口的话记得同步改防火墙规则。

5.2 防火墙放行与安全组

Rocky 9 默认用 firewalld：

sudo firewall-cmd --permanent --add-port=8080/tcp sudo firewall-cmd --reload sudo firewall-cmd --list-ports

Debian 系如果装了 ufw：

sudo ufw allow 8080/tcp sudo ufw status

如果机器在云上，除了系统防火墙，还有一层安全组，得在控制台里把对应端口放行。这两层任何一层没开，外部都连不上。排查的时候先用telnet 目标IP 8080从另一台机器试，通了说明网络层没问题，不通就回去查防火墙。

5.3 内网访问与端口转发的取舍

同网段访问最简单，浏览器直接输http://机器IP:8080就行。如果跨网段，或者你想通过一个统一入口访问多台机器上的服务，那就涉及端口转发。常见做法是在网关机器上用 nginx 做反向代理，把不同路径映射到不同后端。

这里要提醒一句：把服务直接暴露到公网风险很高，Harness Web 本身不一定有完善的鉴权机制。稳妥做法是只在内网开放，需要外部访问时走正规的访问控制方案，别图省事直接映射端口。热词里那些"远程访问"的诉求，落到实操上一定要先想清楚安全边界。

6. 常见故障排查与运维经验

6.1 启动失败类问题速查

这张表基本覆盖了我遇到过的八成启动问题。核心思路就一条：先看日志，日志里写什么就查什么，别瞎猜。

6.2 运行中崩溃与日志分析

服务跑着跑着挂了，Restart=on-failure会把它拉起来，但你不能不管，得搞清楚为什么挂。用这个命令看崩溃前后的日志：

journalctl -u deepseek-harness --since "10 minutes ago" --no-pager

常见崩溃原因有几个：内存不够被 OOM Killer 干掉（日志里会有Out of memory）、模型接口超时导致未捕获异常、SQLite 并发写入锁冲突。内存问题就加内存或者限制并发；超时问题就在配置里调大超时时间；SQLite 锁冲突严重的话，考虑换成 PostgreSQL，但那属于架构调整了。

6.3 性能调优与资源限制

如果机器上还跑着别的服务，你希望 Harness Web 别把资源吃光，可以在 service 单元里加限制：

MemoryMax=2G CPUQuota=150%

MemoryMax限制最大内存，超了会被杀；CPUQuota=150%表示最多用 1.5 个核。这两个参数在共享机器上特别有用，能防止一个服务拖垮整台机器。

日志轮转也值得配一下，虽然 journald 默认会管，但你可以显式限制：

sudo journalctl --vacuum-size=500M

这条命令把日志总量压到 500M 以内，老日志自动清理。对于磁盘紧张的边缘设备，这个操作能救命。

6.4 升级与回滚的稳妥做法

升级时别直接覆盖app目录。正确姿势是先备份：

cp -r /opt/deepseek-harness/app /opt/deepseek-harness/app.bak.$(date +%Y%m%d)

然后把新代码放进去，重新装依赖，重启服务。如果新版本有问题，把app.bak换回来，重启即可回滚。数据库结构如果有变更，升级前一定要备份data目录，SQLite 文件直接复制就行。

我个人的习惯是每次升级前打个快照，哪怕只是tar一下整个目录。花两分钟打包，能省下出问题时几个小时的折腾。

7. 我踩过的坑和几条实在建议

部署这套东西，我前后在不同机器上折腾了七八次，有几个教训是文档里不会写的。

第一个是虚拟环境路径。systemd 单元里ExecStart必须写虚拟环境里 Python 的绝对路径，不能写python。因为 systemd 不读你的 shell 环境变量，PATH里没有 venv，写python它会去找系统 Python，然后报一堆模块找不到。这个坑我踩过两次才记住。

第二个是.env文件的换行符。如果你在 Windows 上编辑过这个文件再传上去，可能带 CRLF 换行，某些解析库会把\r也读进值里，导致配置看起来对但就是不生效。用cat -A .env看一眼，如果行尾有^M，用dos2unix转一下。

第三个是时间同步。Harness Web 记录会话时间戳，如果机器时间不准，日志时间会对不上，排查问题时特别误导。装个 chrony 或者 systemd-timesyncd 把时间同步开起来，这是基础中的基础。

第四个是别在生产机上直接改配置试错。我一般会先在测试机上把流程跑通，确认无误再上生产。生产机上改配置前先cp一份备份，改完systemctl restart后立刻status加journalctl确认，有问题马上回滚。

最后说个扩展方向。这套部署方式跑通之后，你可以把同样的套路用到其他 Python Web 项目上，无非是改改单元文件里的路径和启动命令。把 systemd 单元模板化，以后部署新服务就是复制粘贴改几个字段的事。这个技能一旦掌握，你在 Linux 上托管任何常驻服务都不再发怵。