没有不值得去解决的问题,也没有不值得去学习的技术!

The A Tour of Go Multilingual Translation Project: zh-CN Is Now Live, With a Complete Deployment Record From Production Release to the go.dev Playground

Figure 1: A Tour of Go Simplified Chinese official production page, remote execution has successfully output "Hello, 世界".

作者:

在

After a preceding series of translation, structure preservation, automated validation, public UI localization, and pre-release global acceptance, the A Tour of Go multilingual translation project has finally moved from “content is ready” to the actual production deployment phase.

The Simplified Chinese zh-CN version launched this time has completed:

  • 103/103 course pages;
  • 7/7 article metadata;
  • Public UI localization;
  • production publish;
  • Production static release package;
  • systemd service;
  • Nginx reverse proxy;
  • EdgeOne CDN;
  • HTTPS;
  • Remote execution and formatting;
  • Final browser acceptance.

Official site:

Plaintext
https://go-tour.shuijingwanwq.com/

The focus of this article is no longer the translation itself, but a series of issues encountered when the project entered a production environment for the first time.

Several of these issues would have been almost impossible to fully expose in advance in a local development environment, including:

  • glibc version incompatibility;
  • OneinStack auto-generated Nginx static asset rules hijacking the reverse proxy;
  • Alibaba Cloud ECS unable to access play.golang.org;
  • go.dev Playground API request format differing from the original proxy implementation;
  • Directory permissions after release upload causing systemd 203/EXEC;
  • Running Nginx process disconnecting from systemd PID state.

Ultimately, these issues were resolved one by one, and the production site went live.


1. From 103/103 ready to a real production publish

Before the official deployment, zh-CN had already completed all 103 course pages.

The final status was:

Plaintext
Section: 103/103 ready
article metadata: 7/7

Additionally, the following had been completed previously:

  • present parsing;
  • structure comparison;
  • page rendering;
  • HTTP acceptance;
  • manual browser spot-checking;
  • public UI localization.

Therefore, the production deployment phase no longer involved re-doing translations, but rather started to address a new problem:

How to actually deploy the Chinese content, which had already passed automated validation, as a repeatable, verifiable, and rollback-capable production release.

The final production release package generated by the project included:

Plaintext
bin/tour
_content/
release.json
SHA256SUMS

And recorded:

  • locale;
  • page count;
  • article count;
  • upstream commit;
  • execution method;
  • Go OS / Arch;
  • whether local /socket is enabled.

The production environment explicitly disabled the local code execution API:

Plaintext
local_socket_enabled = false

The run and format features in the browser are proxied by the server to the remote Go Playground.


2. First production issue: GLIBC_2.34 incompatibility

The initially generated bin/tour worked locally, but failed to run after being uploaded to the server.

Further inspection revealed that the glibc on the production server was:

Plaintext
glibc 2.32

While the locally built binary depended on:

Plaintext
GLIBC_2.34

This meant the binary actually carried a higher glibc runtime requirement than the server provided.

For this kind of Go service, the most direct solution was not to upgrade the entire server’s glibc, but to completely eliminate such dynamic dependencies in the production binary.

The final production build explicitly used:

Plaintext
CGO_ENABLED=0

After regenerating the release package:

Plaintext
ELF 64-bit LSB executable
statically linked

Continued inspection with:

Plaintext
ldd bin/tour

Yielded:

Plaintext
not a dynamic executable

The production binary no longer depended on the server’s glibc version.

This also became a fixed build constraint for subsequent production publishes.


3. Official deployment directory and systemd service

To avoid continuing to use the system disk, I ultimately deployed Go Tour at:

Plaintext
/data/go-tour/

Using a release + current symlink structure:

Plaintext
/data/go-tour/
├── current -> releases/20260811-zh-CN-925d59d
└── releases/
    ├── 20260811-zh-CN-0fd1001
    └── 20260811-zh-CN-925d59d

A benefit of this approach is that upgrading versions does not directly overwrite the files currently in use.

After uploading the new version and completing validation, only the following needs to be switched:

Plaintext
/data/go-tour/current

The old release can still be temporarily retained for rollback purposes.

Go Tour itself is run by an independent systemd service:

Plaintext
go-tour.service

Listening only on localhost:

Plaintext
127.0.0.1:3999

External users cannot directly access this port.

The complete request chain is ultimately:

Plaintext
Browser
→ EdgeOne
→ Nginx
→ Go Tour
→ go.dev Playground

4. Page loaded, but CSS and JavaScript all returned 404

After completing the Nginx and EdgeOne integration for the first time, the browser could already access the Chinese course pages.

However, the page was clearly not normal:

  • HTML had content;
  • Chinese text was also normal;
  • CSS was not loaded;
  • JavaScript was not loaded;
  • The entire page was in a near-“bare HTML” state.

Bypassing Nginx, I requested Go Tour directly:

Plaintext
127.0.0.1:3999

CSS and JavaScript both returned 200.

However, requesting the same resources through Nginx returned 404.

Therefore, the problem could already be narrowed down to:

Go Tour itself had no issues; the error occurred in Nginx.

After checking the site configuration auto-generated by OneinStack, I found that in addition to:

Nginx
location / {
    proxy_pass http://127.0.0.1:3999;
}

it also auto-generated regular location for static files.

For example, resources like CSS, JS, and PNG would hit these rules first, instead of entering the location / reverse proxy.

For traditional PHP websites, such rules are very common.

However, Go Tour’s /tour/static/... is actually served by the Go service itself, so these static file rules intercepted the normal requests instead.

Ultimately, I deleted the two sets of static resource location in the site config that were unsuitable for reverse proxy applications, retaining:

Nginx
location / {
    proxy_pass http://127.0.0.1:3999;
}

After reloading Nginx again:

Plaintext
/tour/static/css/app.css → 200
/tour/static/...         → 200
/tour/script.js          → 200

The browser page returned to normal.


5. Page was normal, but the “Run” button reported an error

After resolving the static resource issue, the Chinese page displayed fully.

However, clicking the “Run” button on the right resulted in:

Plaintext
Error communicating with remote server.

Program exited.

At this point, I first needed to distinguish exactly which layer had the problem:

Plaintext
Browser
→ EdgeOne
→ Nginx
→ Go Tour
→ Playground

After checking the frontend script.js, I confirmed that “Run” actually requested:

Plaintext
POST /_/compile?backend=

Formatting corresponded to:

Plaintext
POST /_/fmt?backend=

Directly requesting the local Go Tour:

Plaintext
http://127.0.0.1:3999/_/compile?backend=

Yielded:

Plaintext
HTTP 502

Playground compile unavailable

This step was crucial.

Because the request had already bypassed EdgeOne and Nginx, the problem was unrelated to the CDN and reverse proxy.

The actual failure was:

Go Tour → remote Playground.


6. Production server unable to connect to play.golang.org

At that time, the production proxy was using:

Plaintext
https://play.golang.org

Testing directly on the Alibaba Cloud ECS:

Plaintext
https://play.golang.org/

Result:

Plaintext
HTTP 000

Connection timed out

But testing:

Plaintext
https://go.dev/play/

Returned normally:

Plaintext
HTTP 200

Furthermore, sending actual code directly to:

Plaintext
https://go.dev/_/compile

Successfully returned:

Go
package main

import "fmt"

func main() {
    fmt.Println("Hello, 世界")
}

It successfully returned:

Plaintext
Hello, 世界
Figure 2: The production server cannot connect to the original play.golang.org upstream, while go.dev/_/compile successfully completes remote code execution.
Figure 2: The production server cannot connect to the original play.golang.org upstream, while go.dev/_/compile successfully completes remote code execution.

At this point, the root cause of the production “Run” failure was very clear:

Plaintext
play.golang.org:443
→ Alibaba Cloud ECS connection timed out

go.dev
→ Accessible normally

7. Not just a domain change: go.dev’s API paths and request formats are also different

Initially, it seemed the solution was simply:

Plaintext
play.golang.org
→ go.dev

But when actually modifying the production proxy, I discovered two more details.

1. Different API paths

The new actual APIs were:

Plaintext
https://go.dev/_/compile
https://go.dev/_/fmt

Therefore, the final production upstream base URL used:

Plaintext
https://go.dev/_

The proxy then appended:

Plaintext
/compile
/fmt

2. Compile requests must maintain form encoding

This was an easier detail to overlook during this fix.

The fields passed from the browser to Go Tour included:

Plaintext
version
body
withVet

A request conversion existed in the original proxy.

However, actual verification revealed:

go.dev/_/compile requires the original form request format.

If the request was re-encoded into an incompatible format, even if the remote HTTP layer could respond, it would not return normal execution events.

Therefore, the final modification was not simply replacing a hostname, but rather:

  • changing the production provider to go.dev;
  • using https://go.dev/_/compile for compile;
  • using https://go.dev/_/fmt for fmt;
  • retaining form encoding for compile’s version, body, and withVet;
  • keeping the browser API unchanged;
  • keeping /socket disabled.

After retesting:

Plaintext
/_/compile → 200
/_/fmt     → 200
/socket    → 404
/_/share   → 404

The production release provider was also officially updated to:

Plaintext
execution_provider = go.dev

8. First switch to new release failed: systemd 203/EXEC

After completing the go.dev fix, the new release was uploaded to:

Plaintext
/data/go-tour/releases/20260811-zh-CN-925d59d

Then I switched:

Plaintext
/data/go-tour/current

to the new version.

However, after systemd started, the HTTP health check failed.

Further inspection of the logs revealed:

Plaintext
go-tour.service: Main process exited, code=exited, status=203/EXEC

The meaning of 203/EXEC was very clear:

systemd failed to successfully execute the program specified by ExecStart.

Initially, I suspected the new binary itself might be flawed.

But after comparing the permissions of the old and new releases, I immediately found the real cause:

Old version:

Plaintext
drwxr-xr-x root root

New version:

Plaintext
drwx------ www www

Although:

Plaintext
bin/tour

itself had execute permissions, the go-tour service user could not traverse the upper-level 700 directory, and therefore could not access the binary file at all.

Using:

Plaintext
runuser -u go-tour -- test -x ...

Verification clearly showed:

Plaintext
new: NOT executable by go-tour
old: executable by go-tour

Finally, I normalized the new release to:

Plaintext
root:root
755

Verifying again:

Plaintext
new: executable by go-tour

Then switching again:

Plaintext
current=/data/go-tour/releases/20260811-zh-CN-925d59d
HTTP=200

systemd started normally.


9. Final production release

The final production release used officially was:

Plaintext
20260811-zh-CN-925d59d

Corresponding project commit:

Plaintext
925d59d92016e026c92ae60f4535abd9237119ea

Production status:

Plaintext
locale             : zh-CN
pages              : 103
articles           : 7
execution_provider : go.dev
local_socket       : False

Binary:

Plaintext
ELF 64-bit LSB executable
x86-64
statically linked
Figure 3: zh-CN official production release status: 103 course pages, 7 articles, remote execution using go.dev, local /socket disabled, and production binary using static linking.
Figure 3: zh-CN official production release status: 103 course pages, 7 articles, remote execution using go.dev, local /socket disabled, and production binary using static linking.

10. Nginx was running, but systemd showed failed

Another relatively independent issue was encountered during deployment.

At that time, Nginx was clearly serving normally on:

Plaintext
80
443

But:

Plaintext
nginx.service

showed:

Plaintext
ActiveState=failed
MainPID=0

The actually running master process was:

Plaintext
375418

And:

Plaintext
/var/run/nginx.pid

had become a 0-byte file.

Checking the configuration:

Plaintext
systemd PIDFile=/var/run/nginx.pid
nginx.conf pid=/var/run/nginx.pid

The paths on both sides were actually identical.

The real problem was:

The current Nginx master was not started by systemd’s current cycle, and systemd later tried to start a second Nginx.

Because the old master had already occupied 80/443, the new Nginx naturally failed to start.

Ultimately, I did not directly:

Bash
systemctl restart nginx

Nor did I forcefully kill the old process.

Instead, I first verified:

Plaintext
nginx configuration file ... test is successful

Then:

  1. Found the unique old Nginx master;
  2. Used QUIT for a graceful shutdown;
  3. Confirmed the old master had exited;
  4. Cleaned up the invalid PID file;
  5. systemctl reset-failed nginx.service;
  6. Restarted Nginx via systemd.

Finally:

Plaintext
Active: active (running)
Main PID: 611635

And:

Plaintext
/var/run/nginx.pid
→ 611635

At this point, Nginx officially returned to systemd management.

From then on, I could normally use:

Bash
systemctl reload nginx

Or:

Bash
systemctl restart nginx

11. Final browser acceptance

After all server-side checks were completed, the final step was to return to the actual browser.

Opening:

Plaintext
https://go-tour.shuijingwanwq.com/tour/welcome/1

The Chinese course text, code editor, and page styles were all normal.

After clicking “Run”, the bottom right correctly output:

Plaintext
Hello, 世界

Program exited.

The “Format” button also worked normally.

Figure 1: A Tour of Go Simplified Chinese official production page, remote execution has successfully output "Hello, 世界".
Figure 1: A Tour of Go Simplified Chinese official production page, remote execution has successfully output “Hello, 世界”.

This step was actually very important.

Because we had previously verified separately:

  • Go Tour backend;
  • Nginx;
  • EdgeOne;
  • Playground API.

And actually clicking “Run” and “Format” in the browser is what completes the acceptance of the entire chain from the end-user’s perspective.


12. Final public network smoke testing

After Nginx was brought back under systemd management, I conducted another round of final public network checks.

The results were:

Plaintext
Course page      → HTTP 200
/_/compile      → HTTP 200
Run output      → Hello, 世界
/_/fmt          → HTTP 200
/socket         → HTTP 404

Current release:

Plaintext
20260811-zh-CN-925d59d
Figure 4: Final public network acceptance: course page, remote execution, and formatting are all normal, /socket returns 404, and the official production version is 925d59d.
Figure 4: Final public network acceptance: course page, remote execution, and formatting are all normal, /socket returns 404, and the official production version is 925d59d.

There was also a very interesting minor episode here.

When organizing this blog screenshot for the first time, /_/compile once experienced a transient 502.

To avoid treating an isolated issue directly as a conclusion, I conducted three separate rounds of testing:

Plaintext
Go Tour local direct connection → 5/5 HTTP 200
Nginx origin HTTPS             → 5/5 HTTP 200
EdgeOne public network         → 5/5 HTTP 200

It did not recur.

Therefore, there is currently no evidence indicating a persistent failure in the production execution chain.

This also reminded me:

Deployment acceptance cannot rely on a single success, nor should architecture be modified immediately due to a single sporadic failure. Isolating the chain layer by layer and then observing whether the problem can be consistently reproduced is often more important than directly “fixing” it.


13. Why /tour was ultimately retained

After the official launch, I noticed another minor issue.

The current URLs were:

Plaintext
https://go-tour.shuijingwanwq.com/tour/list
https://go-tour.shuijingwanwq.com/tour/welcome/1

Since the subdomain itself was named:

Plaintext
go-tour

Adding another layer of:

Plaintext
/tour/

did seem a bit redundant at first glance.

Therefore, I specifically analyzed whether it should be changed to:

Plaintext
https://go-tour.shuijingwanwq.com/list
https://go-tour.shuijingwanwq.com/welcome/1

In the end, I decided to:

Retain /tour.

The reason is that /tour is not an extra path layer added during this production deployment, but rather the core routing structure of the official A Tour of Go itself.

It involves:

  • Go HTTP routing;
  • Angular routing;
  • course navigation;
  • TOC;
  • HTML templates;
  • partials;
  • internal course links;
  • static assets;
  • lesson API;
  • preview;
  • webtest;
  • a large number of existing tests.

If /tour were forcibly removed, it would require maintaining an estimated 10 to 15 code, template, and test files.

If the existing /tour/... links within the 103 course pages were also thoroughly cleaned up, it would further impact:

  • English source;
  • zh-CN candidate;
  • source hash;
  • status;
  • catalog.

While the benefit would mainly just be:

A slightly cleaner-looking URL.

For a project that needs to continuously sync with upstream in the long term, this maintenance cost is not worthwhile.

So the official structure was ultimately retained.


14. Final architecture after official launch

The production access chain is now finalized as:

Plaintext
Cloudflare Authoritative DNS
        ↓
Tencent EdgeOne
        ↓
Nginx
        ↓
Go Tour
127.0.0.1:3999
        ↓
go.dev Playground

Cloudflare here only handles authoritative DNS.

The business CNAME uses:

Plaintext
DNS only

No additional Cloudflare Proxy layer is applied, so there is no dual-layer CDN setup with Cloudflare + EdgeOne.

Regarding code execution:

Plaintext
/socket

remains unexposed:

Plaintext
HTTP 404

Run and Format are routed through:

Plaintext
/_/compile
/_/fmt

By the server proxy to:

Plaintext
go.dev

This is also one of the most important security boundaries between the current production architecture and the local development mode.


15. The most valuable lessons worth recording from this launch

At this step, the A Tour of Go multilingual translation project has finally completed the zh-CN phase one launch in the truest sense.

Looking back, the most valuable things to record from this production deployment are not specific commands, but rather a few more general lessons.

1. Passing locally does not mean the production binary will definitely run

If a Go project does not explicitly control CGO, it can still bring system runtime dependencies into the production package.

For production releases, it is best to proactively verify:

Plaintext
file
ldd

Rather than discovering glibc incompatibility only after the server reports an error.

2. Generic Nginx templates are not necessarily suitable for reverse proxy applications

The CSS and JS static asset caching rules generated by OneinStack for ordinary websites are not inherently wrong.

The mistake was:

Applying a set of default assumptions tailored for traditional websites directly onto an application that serves its own static assets via Go.

3. “Changing the domain” does not mean the API is compatible

Migrating from:

Plaintext
play.golang.org

to:

Plaintext
go.dev

Ultimately involved not just changing the domain, but also:

  • paths;
  • form encoding;
  • compile/fmt request behavior;
  • production manifest.

If only the hostname had been changed at that time, it would likely have resulted in a half-finished state where “HTTP 200 is returned, but the actual execution behavior is incorrect.”

4. systemd’s 203/EXEC does not necessarily mean a corrupted binary

The real problem this time was simply:

Plaintext
release root directory 700

Which prevented the service user from traversing the directory.

So when encountering 203/EXEC, in addition to checking the binary itself, you must also check the access permissions on the entire path from the root directory down to the executable file.

5. A single sporadic failure cannot directly be deduced as an architectural fault

A 502 occurred once during the final screenshot stage.

If I had immediately started modifying EdgeOne, Nginx, or Go Tour at that time, it would likely have introduced new problems.

Later, continuous layer-by-layer testing:

Plaintext
5/5
5/5
5/5

Confirmed there was no persistent failure.

This principle of “reproduce first, then fix” is especially important in production environments.


16. A phase has truly ended

From the very beginning of the project, deciding:

To use complete course pages as the minimum translation unit.

To later solving step by step:

  • Section structure preservation;
  • inline code repositioning;
  • link repositioning;
  • emphasis;
  • static code blocks;
  • instructional comments;
  • #appengine: special pages;
  • public UI;
  • article metadata;
  • full validation of 103 pages;
  • production publish;
  • static binary;
  • Nginx;
  • EdgeOne;
  • HTTPS;
  • Playground;
  • systemd;

Until today, actually opening:

Plaintext
https://go-tour.shuijingwanwq.com/

And being able to click in the browser:

Plaintext
Run
Format

Only then did I consider:

The A Tour of Go multilingual translation project’s zh-CN phase one is truly complete.

It is no longer just a:

Plaintext
103/103 ready

local translation project.

It is an official site that can actually be accessed from the public network, can interactively execute code, can continue to track upstream, and retains extensibility for future languages.

The project’s focus can finally shift from:

“How to build the first language”

to:

“How to maintain it long-term, and where the next language should start.”

关于作者 · 持续学习与技术实践

我是一名拥有 15 年以上开发经验的技术从业者,自 2013 年起持续运营个人技术博客,记录工作与个人项目中遇到的真实问题,以及解决问题过程中的探索、实践和思考。

除了技术写作,我也在持续开发和维护自己的独立项目,探索新技术和新工具在实际场景中的应用。我始终相信,没有不值得去解决的问题,也没有不值得去学习的技术。

如果这篇文章对你有所帮助,欢迎浏览博客中的其他文章,也欢迎交流技术经验与想法。

关于我  ·  GitHub  ·  邮件联系