Linux 服务器部署

Linux 服务器适合把已经验证过的 TWS API 程序长期运行起来，例如行情采集、模拟账户联调、定时任务和交易系统后端服务。

对新手来说，推荐路线是：先在 Windows 本机用 TWS 看得见地调通，再把同样的连接逻辑搬到 Linux 服务器。服务器上优先使用 IB Gateway，因为它比完整 TWS 更轻，但它不是“纯后台免登录服务”。它仍然需要图形登录窗口、账号认证、API 端口设置和定期重新认证。

项目	建议	说明
客户端	IB Gateway	服务器上更轻量，适合 API 程序连接。需要人工登录和图形会话。
账户	Paper Account	服务器联调阶段先使用模拟账户，避免误碰真实资金。
API 端口	Paper: `4002`，Live: `4001`	IB Gateway 常用端口。最终以 Gateway 设置页里的 `Socket Port` 为准。
连接地址	`127.0.0.1`	当 Python 程序和 IB Gateway 在同一台服务器上运行时使用。
图形环境	远程桌面 / VNC / 可见桌面会话	需要能看到登录窗口和认证提示。不要只依赖纯 SSH。
程序部署	先手动运行，再考虑守护进程	先确认登录、端口和脚本都通，再做自启动。

部署前先理解限制

TWS API 程序并不是直接连 IBKR 云端。程序连接的是已经运行并登录的 TWS 或 IB Gateway，然后由 TWS / IB Gateway 再连接 IBKR 服务器。

这会带来几个部署约束：

服务器必须能运行 IB Gateway 或 TWS。
登录窗口需要图形界面，安全原因下不支持没有 GUI 的真正 headless 会话。
每日重启、每周重新认证、网络断线都可能让 API 程序暂时不可用。
API Socket 端口只应该暴露给可信程序，不能直接开放到公网。
行情权限、交易权限、账户区域限制仍然由 IBKR 账户决定，换到服务器不会绕过这些限制。

安装 IB Gateway

进入 IBKR 官方下载页，选择 IB Gateway 的 Linux 版本。常见服务器是 Linux (X86_64)，ARM 服务器才选 Linux (ARM64)。

下载后按安装器提示安装即可。安装目录不要写死，脚本和启动命令里都要用自己的实际路径替换：

<你的 IB Gateway 安装目录>/ibgateway

第一次启动建议在远程桌面或 VNC 里手动打开，选择 Paper Account 登录。登录成功后先不要急着跑策略，先进入设置页完成 API 配置。

配置 API 连接

在 IB Gateway 中进入：

Configure → Settings → API → Settings

至少确认这些项目：

设置项	建议	说明
Enable ActiveX and Socket Clients	勾选	允许 API 客户端通过 Socket 连接。
Socket Port	Paper 常用 `4002`	Live 常用 `4001`。不要凭记忆，最终以界面显示为准。
Read-Only API	按用途决定	只读适合行情和账户查询；需要模拟下单或 `whatIf` 时再关闭。
Allow connections from localhost only	同机部署时勾选	Python 后端和 Gateway 在同一台服务器上时最安全。
Trusted IPs	跨机器连接才配置	如果程序不在同一台服务器，必须只加入可信内网 IP。

服务器部署时最容易犯的错误，是为了远程调试把 4001 或 4002 直接放到公网。TWS API Socket 没有设计成公开互联网接口，正确做法是让后端程序和 Gateway 在同一台机器或可信内网中通信，再由网站后端提供受控接口。

安装 Python API 包

TWS API 的 Python 包来自官方 API 软件包，不是随 IB Gateway 自动安装的。安装 TWS API 包后，进入 source/pythonclient 目录执行：

cd "<你的 TWS API 安装目录>/source/pythonclient"
python3 -m pip install .

验证当前 Python 能导入 ibapi：

python3 -c "import ibapi; print(ibapi.__file__)"

如果服务器上同时有多个 Python，不要只看 python3 --version。运行程序用哪个 Python，就用哪个 Python 安装和验证 ibapi。

最小连通验证

IB Gateway 已登录并开启 API 后，可以先用最小脚本验证服务器时间。这个检查只验证 Socket、端口和回调链路，不请求行情，也不下单。

from ibapi.client import EClient
from ibapi.wrapper import EWrapper


class GatewayTimeApp(EWrapper, EClient):
    def __init__(self):
        EClient.__init__(self, self)

    def nextValidId(self, orderId: int):
        # 收到 nextValidId 表示 IB Gateway 已接受这个 API 客户端。
        # 连接准备好以后，再请求服务器时间。
        self.reqCurrentTime()

    def currentTime(self, time_: int):
        # time_ 是 IBKR 服务器时间的 Unix 时间戳。
        print("服务器时间:", time_)
        self.disconnect()

    def error(self, reqId, errorCode, errorString, advancedOrderRejectJson=""):
        # 这里会收到错误、警告和连接状态消息。
        print("Gateway 消息:", reqId, errorCode, errorString)


app = GatewayTimeApp()

# Python 程序和 IB Gateway 在同一台服务器时使用 127.0.0.1。
# 4002 是 IB Gateway 模拟账户常用端口；如果设置页不同，请改成实际端口。
app.connect("127.0.0.1", 4002, clientId=2001)
app.run()

成功时会看到服务器时间输出。连接过程中也可能出现 2104、2106 这类行情场状态消息，它们通常是连接状态提示，不等于脚本失败。

后台运行前的检查清单

在考虑 systemd、计划任务或自启动之前，先逐项确认：

检查项	通过标准
图形会话	能看到 IB Gateway 登录窗口、设置页和重新认证提示。
登录账户	明确当前是 Paper Account 还是 Live Account。
API 端口	设置页端口和代码里的端口一致。
本机连接	`127.0.0.1` 能连通，收到 `nextValidId` 或服务器时间。
Python 环境	运行程序的 Python 可以 `import ibapi`。
断线恢复	程序能识别断线消息，并在 Gateway 恢复后重连或重新订阅。
日志	程序日志和 Gateway 日志能定位连接失败、认证失败和端口错误。

稳定运行不是只靠“进程不退出”。TWS API 程序还要处理 IBKR 服务器维护、Gateway 自动重启、每周认证、行情订阅丢失和订单状态同步。

常见问题

现象	常见原因	处理方式
SSH 里能启动命令，但看不到登录窗口	没有图形桌面会话或 `DISPLAY` 环境不对。	先用远程桌面或 VNC 手动启动并登录。
`502 Couldn't connect to TWS`	Gateway 没运行、API 没开启、端口不一致或防火墙阻止。	检查 `Enable ActiveX and Socket Clients`、`Socket Port` 和本机防火墙。
Windows 能连，Linux 不能连	端口从 TWS 的 `7497` 换成 Gateway 的 `4002` 后代码没改。	按服务器 Gateway 设置页里的端口修改代码。
服务器运行几天后断开	每日重启、每周重新认证或网络维护。	程序要能重连；认证提示需要人工处理。
远程机器连不上 Gateway	勾选了只允许本机连接，或 Trusted IPs 没配置。	同机部署保持 `localhost only`；跨机器只放行可信内网 IP。
行情或订单结果和本机不一致	账户、权限、环境、客户端版本或登录类型不同。	先确认同一账号、同一 Paper/Live 类型和同一 API 版本。

官方依据

IBKR TWS API Documentation：官方说明 TWS API 需要连接已运行的 TWS 或 IB Gateway，并通过 Socket 端口通信。
IB Gateway Download：官方提供 IB Gateway 的 Linux X86_64 和 ARM64 下载入口。